cloud
2.3 KiB
2.3 KiB
name, description
| name | description |
|---|---|
| edge-python-agent | edge_collector Python 独立 agent 开发规范。用于新增或修改 frpc agent、port forward agent、WiFi/4G 辅助进程、巡检脚本、数据分析脚本等 Python3 常驻或命令行工具时，统一配置、日志、systemd、资源占用、退出码和与 edge 主服务解耦要求。 |
edge_collector Python Agent
适用范围
scripts/frp/start_*.pyscripts/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
服务文件应明确：
WorkingDirectory
ExecStart
Restart=on-failure
RestartSec
User
Environment
新增服务应独立，不替代已有 edge、frpc_agent 或其他服务，除非用户明确要求迁移。
CLI
建议支持：
--config <path>
--log-level <level>
--once
--dry-run
--once 适合调试和安装后验证。
验证
至少验证：
python3 -m py_compile scripts/<dir>/<file>.py
python3 scripts/<dir>/<file>.py --help
常驻服务验证：
systemctl status <service> --no-pager
journalctl -u <service> --since "5 min ago" --no-pager