cloud
89 lines
2.3 KiB
Markdown
89 lines
2.3 KiB
Markdown
---
|
|
name: edge-python-agent
|
|
description: edge_collector Python 独立 agent 开发规范。用于新增或修改 frpc agent、port forward agent、WiFi/4G 辅助进程、巡检脚本、数据分析脚本等 Python3 常驻或命令行工具时，统一配置、日志、systemd、资源占用、退出码和与 edge 主服务解耦要求。
|
|
---
|
|
|
|
# edge_collector Python Agent
|
|
|
|
## 适用范围
|
|
|
|
- `scripts/frp/start_*.py`
|
|
- `scripts/port_forward/start_*.py`
|
|
- WiFi/4G 辅助脚本。
|
|
- 远程巡检和数据分析脚本。
|
|
- 需要 systemd 托管的 Python 常驻进程。
|
|
|
|
## 命名与位置
|
|
|
|
- 常驻启动脚本使用 `start_` 前缀，保持现有风格。
|
|
- 按功能放到独立目录，例如 `scripts/frp/`、`scripts/port_forward/`。
|
|
- 不要把独立 agent 代码塞进 `collector` 或 `configurator`。
|
|
|
|
## 配置
|
|
|
|
- 配置文件放到运行目录的 `config/` 或功能子目录。
|
|
- 支持配置缺失时生成默认文件，但不得覆盖已有配置。
|
|
- 动态配置必须被打包和同步规则排除，避免目标主机运行配置被覆盖。
|
|
- 密钥、Token、URL 不写死在代码中。
|
|
|
|
## 日志
|
|
|
|
- 使用 Python `logging`。
|
|
- 日志包含时间、级别、模块、关键状态。
|
|
- 不打印密钥、密码、Token。
|
|
- 高频循环日志要限流，避免 CPU/磁盘压力。
|
|
- 错误日志要保留具体原因，供前端展示更明确错误。
|
|
|
|
## 常驻进程要求
|
|
|
|
- 支持优雅退出 `SIGTERM`/`SIGINT`。
|
|
- 主循环有固定 sleep 或事件等待，禁止无休眠空转。
|
|
- 外部命令调用设置 timeout。
|
|
- 子进程必须回收。
|
|
- 网络请求必须设置连接和读取超时。
|
|
- 异常后退避重试，不要短时间无限重启。
|
|
|
|
## systemd
|
|
|
|
服务文件应明确：
|
|
|
|
```text
|
|
WorkingDirectory
|
|
ExecStart
|
|
Restart=on-failure
|
|
RestartSec
|
|
User
|
|
Environment
|
|
```
|
|
|
|
新增服务应独立，不替代已有 `edge`、`frpc_agent` 或其他服务，除非用户明确要求迁移。
|
|
|
|
## CLI
|
|
|
|
建议支持：
|
|
|
|
```bash
|
|
--config <path>
|
|
--log-level <level>
|
|
--once
|
|
--dry-run
|
|
```
|
|
|
|
`--once` 适合调试和安装后验证。
|
|
|
|
## 验证
|
|
|
|
至少验证：
|
|
|
|
```bash
|
|
python3 -m py_compile scripts/<dir>/<file>.py
|
|
python3 scripts/<dir>/<file>.py --help
|
|
```
|
|
|
|
常驻服务验证：
|
|
|
|
```bash
|
|
systemctl status <service> --no-pager
|
|
journalctl -u <service> --since "5 min ago" --no-pager
|
|
```
|