mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-06 23:56:37 +08:00
ryan
85 lines
5.3 KiB
Markdown
85 lines
5.3 KiB
Markdown
# Agent Unified OpenResty Binary Control Scheme
|
|
|
|
## Summary
|
|
|
|
Unify the Agent running model as "write to the managed configuration file, then call the `openresty` binary to execute `-t`, reload, start/restart". Docker deployment no longer has the Agent control another OpenResty container, but instead provides an independent `ghcr.io/rain-kl/openflare-agent` image; this image is based on `openresty/openresty`, with the Agent controller and OpenResty binary built-in.
|
|
|
|
## Key Changes
|
|
|
|
- Agent runtime:
|
|
- Remove the DockerExecutor / Docker container management logic from the production path.
|
|
- Default to using `openresty` when `openresty_path` is not configured.
|
|
- Uniformly execute binary calls with `-c <main_config_path>` to avoid misreading the OpenResty default configuration.
|
|
- The apply flow is: backup -> write files -> `openresty -t -c ...` -> reload; if reload indicates it is not running, then start.
|
|
- restart uses `openresty -c ... -s quit` followed by `openresty -c ...` to start, keeping fault tolerance for missing PIDs.
|
|
|
|
- Configurations and File Responsibilities:
|
|
- Keep parser compatibility for old fields `openresty_container_name`, `openresty_docker_image`, and `docker_binary`, but mark them as deprecated and no longer involved in control logic.
|
|
- Add `access_log_path`, defaulting to `data_dir/var/log/openflare/access.log`, and no longer placing access logs inside `conf.d`.
|
|
- Add `runtime_config_dir`, defaulting to `data_dir/etc/openflare`, where `pow_config.json` is written.
|
|
- `cert_dir` only writes certificate/key files; `lua_dir` only writes Lua code and static resources.
|
|
- Support splitting files before writing: certificate files go into `cert_dir`, and `pow_config.json` goes into `runtime_config_dir`.
|
|
|
|
- Docker Agent Image:
|
|
- Add `openflare_agent/Dockerfile`, with the runtime image based on `openresty/openresty:alpine`.
|
|
- Defaults to `OPENFLARE_OPENRESTY_PATH=openresty` and `OPENFLARE_DATA_DIR=/data`.
|
|
- Expose `80`, `443`, and `18081`.
|
|
- Support mounting `/etc/openflare/agent.json`, and also support environment variable configurations.
|
|
- CI publishes independent multi-architecture images: `ghcr.io/rain-kl/openflare-agent:<version>` and `latest`.
|
|
|
|
- Agent Configuration Entry:
|
|
- Keep `-config` + `agent.json`.
|
|
- Add environment variable overrides/fallbacks: `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`.
|
|
- If the configuration file does not exist but environment variables are sufficient, the Agent can start directly; if both exist, environment variables override file values.
|
|
|
|
- Scripts and Documentation:
|
|
- `install-agent.sh` becomes a local OpenResty deployment script, adding `--openresty-path` and automatically finding `openresty` when not passed.
|
|
- `uninstall-agent.sh` only uninstalls the Agent itself, and no longer deletes the Docker OpenResty container or image.
|
|
- Update architecture, development constraints, deployment instructions, Agent guide, configuration item reference, README, and old Docker control descriptions in English image documents.
|
|
|
|
## Public Interfaces
|
|
|
|
- Add Agent configuration fields:
|
|
- `access_log_path`
|
|
- `runtime_config_dir`
|
|
|
|
- Deprecated but compatibly read:
|
|
- `openresty_container_name`
|
|
- `openresty_docker_image`
|
|
- `docker_binary`
|
|
|
|
- Add Docker image:
|
|
- `ghcr.io/rain-kl/openflare-agent`
|
|
|
|
- Target Docker execution method examples:
|
|
- Mount configuration file: `-v ./agent.json:/etc/openflare/agent.json`
|
|
- Or environment variables: `-e OPENFLARE_SERVER_URL=... -e OPENFLARE_AGENT_TOKEN=...`
|
|
|
|
## Test Plan
|
|
|
|
- `openflare_agent/internal/config`:
|
|
- Default `openresty_path` is `openresty`.
|
|
- Old Docker fields can be read but do not affect the executor.
|
|
- Environment variables can start the Agent without a configuration file and can override the configuration file.
|
|
- New default paths conform to responsibility boundaries.
|
|
|
|
- `openflare_agent/internal/nginx`:
|
|
- Binary commands all include `-c <main_config_path>`.
|
|
- Apply success, reload failure rollback, and start fallback when not running.
|
|
- `pow_config.json` is no longer written to `cert_dir` or `lua_dir`.
|
|
- Stale `cert_dir/pow_config.json` and `lua_dir/pow_config.json` will be cleaned up.
|
|
- access log is rendered to `access_log_path`.
|
|
- checksum can still uniformly include the main config, route config, certificates, and PoW config into comparisons.
|
|
|
|
- Integration Regression:
|
|
- `cd openflare_agent && GOCACHE=/tmp/openflare-go-cache go test ./...`
|
|
- `cd openflare_server && GOCACHE=/tmp/openflare-go-cache go test ./...`
|
|
- Dockerfile build smoke test: build the Agent image and start it using env-only configuration to the executable stage.
|
|
|
|
## Assumptions
|
|
|
|
- Docker Agent image name is fixed as `ghcr.io/rain-kl/openflare-agent`.
|
|
- Old Docker control fields are compatibly preserved but are no longer a supported behavior.
|
|
- This phase does not modify Server APIs, does not modify database models, and does not introduce remote command capabilities.
|
|
- The OpenResty main configuration template continues to be generated by the Server; the Agent is only responsible for local path replacement, file landing, and binary control.
|