mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-05 07:26:36 +08:00
ryan
87 lines
4.7 KiB
Markdown
87 lines
4.7 KiB
Markdown
# Agent Unified OpenResty Binary Control Scheme
|
||
|
||
# Agent 统一 OpenResty 二进制控制方案
|
||
|
||
## Summary
|
||
|
||
将 Agent 运行模型统一为“写入受管配置文件，然后调用 `openresty` 二进制执行 `-t`、reload、start/restart”。Docker 部署不再由 Agent 控制另一个 OpenResty 容器，而是提供独立的 `ghcr.io/rain-kl/openflare-agent` 镜像；该镜像基于 `openresty/openresty`，内置 Agent 控制器和 OpenResty 二进制。
|
||
|
||
## Key Changes
|
||
|
||
- Agent runtime：
|
||
- 移除生产路径中的 DockerExecutor / Docker 容器管理逻辑。
|
||
- `openresty_path` 未配置时默认使用 `openresty`。
|
||
- 二进制执行统一带 `-c <main_config_path>`，避免误读 OpenResty 默认配置。
|
||
- apply 流程为：备份 -> 写入文件 -> `openresty -t -c ...` -> reload；若 reload 表明未运行，则 start。
|
||
- restart 使用 `openresty -c ... -s quit` 后再 `openresty -c ...` 启动，保留缺失 PID 的容错。
|
||
|
||
- 配置与文件职责：
|
||
- 保留旧字段 `openresty_container_name`、`openresty_docker_image`、`docker_binary` 的解析兼容，但标记废弃且不再参与控制逻辑。
|
||
- 新增 `access_log_path`，默认 `data_dir/var/log/openflare/access.log`，不再把访问日志放进 `conf.d`。
|
||
- 新增 `runtime_config_dir`，默认 `data_dir/etc/openflare`，`pow_config.json` 写入这里。
|
||
- `cert_dir` 只写证书/密钥文件；`lua_dir` 只写 Lua 代码与静态资源。
|
||
- 支持文件写入前先拆分：证书文件进入 `cert_dir`，`pow_config.json` 进入 `runtime_config_dir`。
|
||
|
||
- Docker Agent 镜像：
|
||
- 新增 `openflare_agent/Dockerfile`，运行镜像基于 `openresty/openresty:alpine`。
|
||
- 默认 `OPENFLARE_OPENRESTY_PATH=openresty`、`OPENFLARE_DATA_DIR=/data`。
|
||
- 暴露 `80`、`443`、`18081`。
|
||
- 支持挂载 `/etc/openflare/agent.json`，也支持环境变量配置。
|
||
- CI 发布独立多架构镜像：`ghcr.io/rain-kl/openflare-agent:<version>` 和 `latest`。
|
||
|
||
- Agent 配置入口：
|
||
- 保留 `-config` + `agent.json`。
|
||
- 新增环境变量覆盖/兜底：`OPENFLARE_SERVER_URL`、`OPENFLARE_AGENT_TOKEN`、`OPENFLARE_DISCOVERY_TOKEN`、`OPENFLARE_NODE_NAME`、`OPENFLARE_NODE_IP`、`OPENFLARE_DATA_DIR`、`OPENFLARE_OPENRESTY_PATH`、`OPENFLARE_HEARTBEAT_INTERVAL`、`OPENFLARE_REQUEST_TIMEOUT`、`OPENFLARE_OPENRESTY_OBSERVABILITY_PORT`。
|
||
- 若配置文件不存在但环境变量足够，Agent 可直接启动；若两者都存在，环境变量覆盖文件值。
|
||
|
||
- 脚本与文档：
|
||
- `install-agent.sh` 转为本地 OpenResty 部署脚本，增加 `--openresty-path`，未传时自动查找 `openresty`。
|
||
- `uninstall-agent.sh` 只卸载 Agent 本身，不再删除 Docker OpenResty 容器或镜像。
|
||
- 更新架构、开发约束、部署说明、Agent 指南、配置项参考、README，以及英文镜像文档中的旧 Docker 控制说明。
|
||
|
||
## Public Interfaces
|
||
|
||
- 新增 Agent 配置字段：
|
||
- `access_log_path`
|
||
- `runtime_config_dir`
|
||
|
||
- 废弃但兼容读取：
|
||
- `openresty_container_name`
|
||
- `openresty_docker_image`
|
||
- `docker_binary`
|
||
|
||
- 新增 Docker 镜像：
|
||
- `ghcr.io/rain-kl/openflare-agent`
|
||
|
||
- Docker 运行方式示例目标：
|
||
- 挂载配置文件：`-v ./agent.json:/etc/openflare/agent.json`
|
||
- 或环境变量：`-e OPENFLARE_SERVER_URL=... -e OPENFLARE_AGENT_TOKEN=...`
|
||
|
||
## Test Plan
|
||
|
||
- `openflare_agent/internal/config`：
|
||
- 默认 `openresty_path` 为 `openresty`。
|
||
- 旧 Docker 字段可读取但不影响 executor。
|
||
- 环境变量可在无配置文件时启动，并可覆盖配置文件。
|
||
- 新默认路径符合职责边界。
|
||
|
||
- `openflare_agent/internal/nginx`：
|
||
- 二进制命令都包含 `-c <main_config_path>`。
|
||
- apply 成功、reload 失败后回滚、未运行时 start fallback。
|
||
- `pow_config.json` 不再写入 `cert_dir` 或 `lua_dir`。
|
||
- stale `cert_dir/pow_config.json` 与 `lua_dir/pow_config.json` 会被清理。
|
||
- access log 渲染到 `access_log_path`。
|
||
- checksum 仍能把主配置、路由配置、证书和 PoW 配置统一纳入比较。
|
||
|
||
- 集成回归：
|
||
- `cd openflare_agent && GOCACHE=/tmp/openflare-go-cache go test ./...`
|
||
- `cd openflare_server && GOCACHE=/tmp/openflare-go-cache go test ./...`
|
||
- Dockerfile 构建 smoke test：构建 Agent 镜像并用 env-only 配置启动到可执行阶段。
|
||
|
||
## Assumptions
|
||
|
||
- Docker Agent 镜像名固定为 `ghcr.io/rain-kl/openflare-agent`。
|
||
- 旧 Docker 控制字段保留兼容，但不再作为受支持行为。
|
||
- 本次不改 Server API、不改数据库模型、不引入远程命令能力。
|
||
- OpenResty 主配置模板继续由 Server 生成；Agent 只负责本地路径替换、文件落盘和二进制控制。
|