flnxi-Wu/flnxi-agent/README.md
2026-05-25 17:06:22 +08:00

96 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# FLNXI Agent
FLNXI 素材系统历史 Node 版安装助手。
当前定位:Node 版 Agent 只用于查历史实现和维护已有交付链路,不作为新客户默认安装入口。新交付优先评估 `flnxi-agent-go/`,不要把两个 Agent 同时暴露到同一台机器的公网入口。
正式客户安装、升级和发布不要照抄本目录的镜像名或命令。当前项目主线应以 `deploy-registry.ps1`、`docker-compose.prod.yml` 和明确版本号的镜像为准。
## 功能
- 🚀 一键安装素材系统及所有依赖
- 📊 实时安装进度显示
- 🔄 系统更新和回滚
- 📈 系统状态监控
- 📝 日志查看
## 历史调试方式
### Docker 调试运行
```bash
docker run -d \
--name flnxi-agent \
-p 127.0.0.1:3080:3080 \
-v /var/run/docker.sock:/var/run/docker.sock \
-e AGENT_AUTH_USERNAME=admin \
-e AGENT_AUTH_PASSWORD='<generate-a-strong-random-password>' \
flnxi/flnxi-agent:latest
```
默认只发布到宿主机回环地址,适合本机浏览器或反向代理访问。
这个镜像名保留的是旧链路习惯,不代表当前客户交付主线已经切到它,也不代表可以用 `latest` 做正式升级依据。
如果确实需要局域网直连,再显式改成 `-p 0.0.0.0:3080:3080`(或你自己的内网 IP)。
必须同时配置 `AGENT_AUTH_USERNAME` 和 `AGENT_AUTH_PASSWORD`。未配置时,除了 `/api/health` 之外的页面、API 和 WebSocket 都会默认关闭。
### 本地开发
```bash
# 安装依赖
npm install
cd frontend && npm install && cd ..
# 开发模式
npm run dev
# 构建
npm run build
```
## 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| PORT | Agent 服务端口 | 3080 |
| LICENSE_SERVER_URL | 许可证服务器地址 | https://license.flnxi.com |
| LICENSE_PROJECT_CODE | 当前 Agent 所属项目编码,用于命中对应项目的版本/验证链路 | 未设置 |
| AGENT_AUTH_USERNAME | Agent 管理账号,需和密码同时设置,否则管理面默认关闭 | 未设置 |
| AGENT_AUTH_PASSWORD | Agent 管理密码,需和账号同时设置,否则管理面默认关闭 | 未设置 |
| AGENT_ALLOWED_ORIGINS | 额外允许的 Origin,逗号分隔,主要用于特殊开发/反向代理场景 | 未设置 |
说明:
- `LICENSE_PROJECT_CODE` 未配置时,版本检查链路会报错,不只是“跳过版本检查”。
- 示例里的 `AGENT_AUTH_PASSWORD` 只是占位值,正式环境必须替换成强随机密码。
## 安全建议
- 生产环境必须设置 `AGENT_AUTH_USERNAME` 和 `AGENT_AUTH_PASSWORD`
- Docker 运行时建议默认使用 `-p 127.0.0.1:3080:3080`,仅在明确需要时才改为局域网暴露
- 如果 Agent 需要暴露到局域网,优先通过反向代理或访问控制进一步限制来源
- 未配置认证时,除了 `/api/health` 以外的管理面会直接返回 `503`
- 安装流程会为 PostgreSQL、MinIO 和主应用自动生成随机内部凭据,不再使用源码里写死的弱默认值
## 架构
```
flnxi-agent/
├── src/ # 后端代码
│ ├── server.ts # Express 服务
│ ├── installer.ts # 安装逻辑
│ └── system-manager.ts # 系统管理
├── frontend/ # 前端代码 (React + Vite)
│ └── src/
│ ├── App.tsx
│ └── pages/
│ ├── Welcome.tsx
│ ├── Config.tsx
│ ├── Installing.tsx
│ ├── Complete.tsx
│ └── Dashboard.tsx
└── Dockerfile # 多架构构建
```