FLNXI Agent Go

flnxi-agent-go 是面向私有化部署场景的 Go 版安装与运维 Agent。

当前定位：Go 版 Agent 更适合作为后续私有化交付的轻量入口；它已经收紧了 Agent 自身认证、主应用固定版本镜像和许可证运行参数，但管理界面、安装向导、异常恢复和客户现场验收流程仍未完全闭环，不能直接当成“已经可正式交付”的成品。若现场仍使用 Node 版 Agent，先确认既有安装链路和端口占用，再决定是否切换。

重要现状：

install.sh 已不再默认拉取旧 Harbor latest 镜像，必须通过 AGENT_IMAGE 或 --image 显式传入完整 Agent 版本镜像。
Go 版 Agent 内部安装和更新素材系统已改为读取完整版本镜像，不再默认拉取旧 Harbor / latest。
安装素材系统时必须提供完整主应用版本镜像，不能使用无版本 tag 或 latest。
安装素材系统时必须提供许可证服务参数；缺少关键参数时会在拉镜像前失败，避免客户装出一个启动不了的半成品。
已提供付费模块最小运行入口：POST /api/modules/sync 会使用验证系统签发的短期拉包凭证拉取模块镜像、校验 digest、启动模块容器并在健康检查失败时尝试恢复旧模块容器。
版本列表需要通过 FLNXI_VERSION_LIST_URL 显式配置来源；未配置时不会伪造 latest 或默认版本。
当前仍建议先作为内部验证入口，等管理界面和客户安装流程联调完成后，再提升为客户正式安装主入口。

它负责：

安装素材系统运行环境
执行更新
拉取和运行已授权的付费模块容器
管理相关 Docker 容器
提供内置 Web 界面和 API

运行方式

Docker 运行

docker run -d \
  --name flnxi-agent-go \
  -p 127.0.0.1:9090:9090 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e AGENT_AUTH_USERNAME=admin \
  -e AGENT_AUTH_PASSWORD='<generate-a-strong-random-password>' \
  registry.example.com/flnxi/agent:1.0.1

默认只发布到宿主机回环地址，适合本机浏览器或反向代理访问。

如果确实需要局域网直连，再显式改成 -p 0.0.0.0:9090:9090（或你自己的内网 IP）。

如果使用仓库里的 install.sh 一键安装脚本，默认端口 9090 被占用时会自动递增查找下一个可用端口，并在安装完成后打印最终访问地址。

重要现状：

当前 install.sh 会把环境里的 AGENT_AUTH_USERNAME / AGENT_AUTH_PASSWORD 透传进容器，但要求两者同时存在。
如果没有同时设置这两个变量，安装完成后除 /api/health 外的管理页面和 API 仍会关闭。
如果要直接使用管理面，建议在执行安装脚本前先准备好这两个环境变量，或显式改用上面的 Docker 命令。

必须同时设置 AGENT_AUTH_USERNAME 和 AGENT_AUTH_PASSWORD。未配置时，除了 /api/health 以外的页面和 API 都会默认关闭。

环境变量

变量	说明	默认值
`PORT`	Agent 监听端口	`9090`
`AGENT_AUTH_USERNAME`	Agent 管理账号，需和密码同时设置，否则管理面默认关闭	未设置
`AGENT_AUTH_PASSWORD`	Agent 管理密码，需和账号同时设置，否则管理面默认关闭	未设置
`AGENT_VERSION`	Agent 版本号，用于健康检查返回	未设置
`GIN_MODE`	Gin 运行模式	`release`
`AGENT_IMAGE`	`install.sh` 使用的完整 Agent 版本镜像，也可通过 `--image` 传入	未设置
`FLNXI_MATERIAL_IMAGE`	安装素材系统时使用的完整主应用版本镜像；也兼容读取 `APP_IMAGE`	未设置
`FLNXI_MATERIAL_IMAGE_REPOSITORY`	更新时按版本号拼接的主应用镜像仓库，例如 `registry.example.com/flnxi/material/flnxi-material`	未设置
`FLNXI_POSTGRES_IMAGE`	安装时使用的 PostgreSQL 镜像；也兼容读取 `POSTGRES_IMAGE`	`postgres:15-alpine`
`FLNXI_MINIO_IMAGE`	安装时使用的 MinIO 镜像；也兼容读取 `MINIO_IMAGE`	`minio/minio:RELEASE.2025-04-22T22-12-26Z`
`FLNXI_VERSION_LIST_URL`	Agent 管理界面可选版本列表来源，返回 Registry tags 结构	未设置
`FLNXI_MODULE_NETWORK`	付费模块容器默认加入的 Docker 网络	`flnxi-network`
`FLNXI_MODULE_STATUS_CALLBACK_URL`	付费模块运行状态变化时回调主应用的接口地址；未配置时不回调	未设置
`FLNXI_MODULE_STATUS_CALLBACK_TOKEN`	付费模块状态回调使用的 Bearer token；需和回调地址同时配置，不会写入日志	未设置
`LICENSE_SERVER_URL`	主应用许可证服务地址，安装素材系统时会写入主应用容器	未设置
`LICENSE_PROJECT_CODE`	主应用许可证项目编码，安装素材系统时会写入主应用容器	未设置
`LICENSE_REQUEST_SIGNING_SECRET`	主应用请求许可证服务的签名密钥，至少 32 字符	未设置
`LICENSE_PUBLIC_KEY`	主应用验签用许可证公钥	未设置
`LOCAL_ENCRYPTION_KEY`	主应用本地许可证缓存加密密钥，至少 32 字符；未传入时 Agent 会为本次安装生成	自动生成

版本说明：

当前 Go 版 Agent 的版本列表不再写死 Harbor；后续正式交付前，需要决定版本列表来自 Registry tags、许可证服务，还是发布管理接口。
Go 版 Agent 目前会把主应用启动必需的许可证配置写入容器，但还没有把“许可证服务可安装版本、灰度版本、客户授权版本范围”做成最终客户安装向导。

付费模块运行接口

主应用负责从许可证服务同步模块授权清单、模块授权凭证和短期拉包 token。Go Agent 不判断客户是否付费，只接收已经由主应用/验证系统准备好的模块运行请求：

POST /api/modules/sync
GET  /api/modules/status

POST /api/modules/sync 至少需要：

{
  "moduleId": "paid-core",
  "image": "registry.example.com/flnxi/premium/paid-core:1.0.0",
  "digest": "sha256:...",
  "pullCredential": {
    "registryHost": "registry.example.com",
    "repository": "flnxi/premium/paid-core",
    "tag": "1.0.0",
    "digest": "sha256:...",
    "username": "flnxi-module",
    "pullToken": "<15分钟短期token>",
    "expiresAt": "2026-06-02T00:15:00Z"
  }
}

Agent 会拒绝过期 token、镜像地址不匹配、digest 不匹配或缺少固定版本 tag 的请求。模块容器默认加入 flnxi-network，也可以用 FLNXI_MODULE_NETWORK 或请求里的 network 覆盖；默认容器名为 flnxi-module-{moduleId}。如健康检查失败，会尝试恢复旧模块容器。

模块状态变化时，Agent 会先更新本地 GET /api/modules/status 可见的状态。如果同时配置了 FLNXI_MODULE_STATUS_CALLBACK_URL 和 FLNXI_MODULE_STATUS_CALLBACK_TOKEN，Agent 会向主应用回调地址发送 POST 请求，并在请求头里带上 Authorization: Bearer <token>。通过 Agent 安装主应用时，如果没有显式配置回调地址，安装流程会为本次安装生成回写 token，并按主应用访问地址生成默认回调地址。请求体为：

{
  "moduleId": "paid-core",
  "image": "registry.example.com/flnxi/premium/paid-core:1.0.0",
  "digest": "sha256:...",
  "status": "running",
  "lastSyncAt": "2026-06-02T00:20:00Z",
  "lastError": ""
}

未同时配置回调地址和 token 时，Agent 保持现有行为，只在本地保存模块状态，不主动通知主应用。回调失败不会改变模块本地运行状态，主应用仍可通过 GET /api/modules/status 主动查询。

安装素材系统前，至少要给 Agent 容器配置：

-e FLNXI_MATERIAL_IMAGE=registry.example.com/flnxi/material/flnxi-material:1.0.1
-e FLNXI_MATERIAL_IMAGE_REPOSITORY=registry.example.com/flnxi/material/flnxi-material
-e LICENSE_SERVER_URL=https://license.example.com
-e LICENSE_PROJECT_CODE=flnxi-sucai
-e LICENSE_REQUEST_SIGNING_SECRET='<at-least-32-characters>'
-e LICENSE_PUBLIC_KEY='<license-public-key>'

安全建议

生产环境必须设置 AGENT_AUTH_USERNAME 和 AGENT_AUTH_PASSWORD
Docker 运行时建议默认使用 -p 127.0.0.1:9090:9090，仅在明确需要时才改为局域网暴露
该 Agent 可以直接控制 Docker，不应直接暴露到公网
更推荐放在内网、反向代理后面，或额外加局域网 ACL / 防火墙限制来源
当前认证是基础收口，不等于可以忽略后续的口令管理、网络隔离和审计
未配置认证时，除了 /api/health 以外的管理面会直接返回 503
安装流程现在会为 PostgreSQL、MinIO 和主应用自动生成随机内部凭据，不再内置固定弱口令

开发验证

如果本机没有安装 Go，可以用容器做最小编译验证：

docker run --rm \
  -v "$PWD:/app" \
  -w /app \
  golang:1.22-alpine \
  sh -c "go test ./internal/api -run TestDoesNotExist && go test . -run TestDoesNotExist"

8.8 KiB Raw Permalink Blame History Unescape Escape