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

重要现状：

install.sh 已不再默认拉取旧 Harbor latest 镜像，必须通过 AGENT_IMAGE 或 --image 显式传入完整 Agent 版本镜像。
Go 版 Agent 内部安装和更新素材系统已改为读取完整版本镜像，不再默认拉取旧 Harbor / latest。
安装素材系统时必须提供完整主应用版本镜像，不能使用无版本 tag 或 latest。
安装素材系统时必须提供许可证服务参数；缺少关键参数时会在拉镜像前失败，避免客户装出一个启动不了的半成品。
版本列表需要通过 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 结构	未设置
`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 目前会把主应用启动必需的许可证配置写入容器，但还没有把“许可证服务可安装版本、灰度版本、客户授权版本范围”做成最终客户安装向导。

安装素材系统前，至少要给 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"

README.md Unescape Escape

FLNXI Agent Go

运行方式

Docker 运行

环境变量

安全建议

开发验证

README.md