企业管理智能体完整部署手册

采用“一份私密配置、三个配置组、独立进程”的交付方式。先跑通文字对话和平台业务查询，再按需接入 OCR/ASR。无需 License、公钥、体验码，也不增加 Nacos 或配置中心。

STANDARD DEPLOYMENT

企业管理 + AI 协同部署架构

员工身份全链路透传

◉

员工浏览器https://客户域名/ai/

HTTPS

◆

统一入口 · Nginx / Ingress证书、域名、SSE 长连接统一治理

/ai/→智能体前端

/admin-api/agentos/**→智能体后端

/admin-api/**→一体化平台

应用层

AI WORKSPACE独立扩展服务

企业管理智能体 AgentOS

Web :8080Server :48091

• 对话、知识库、智能体与技能
• HITL 确认、能力编排与审计
• 独立发布、授权与版本升级

↔当前员工 Token权限与数据范围仍由 RuoYi Office 平台校验

BUSINESS PLATFORM业务事实源

RuoYi Office 一体化平台

Server :48080OAuth2 / BPM

• 组织、员工、租户与数据权限
• OA、HRM、Finance 等业务接口
• 事务、幂等与单据状态最终裁决

AgentOS 安全连接

▦

独立数据层AgentOS MySQL Schema
Redis 独立 DB 与前缀

✦

通用大模型 APIOpenAI 兼容协议
主模型 + 备用模型

◎

小模型服务OCR 必选于发票场景
ASR 按需启用

◇

企业文件服务仅允许白名单域名
附件不经过任意公网抓取

边界原则AgentOS 不持有 RuoYi Office 平台数据库账号，不使用超级账号代替员工，不把 OCR / ASR 端口暴露到公网。

1. 交付与环境

取得兼容版本的 AgentOS 与一体化平台源码，平台应已可正常登录。生产建议 Ubuntu 22.04/24.04、Docker 24+、Compose v2.20+、MySQL 8、Redis 6/7、Nginx 与 HTTPS。应用建议 2～4 核、4GB 起，模型服务资源另算。

配置工具需要 Node.js 22.12+；源码编译另需 JDK 17、Maven 3.9+。前端镜像内使用锁定 pnpm 10.33.0。AgentOS 独立 Schema/账号，Redis 独立 database，可复用客户现有实例；不持有平台数据库账号。

约定 AgentOS 在 /opt/agentos-src，平台后端在 /opt/ruoyi-office-src。保留仓库结构，不要只复制 deploy 目录，安装脚本需要 tools 和 SQL 模板。

2. 照着单机部署 Demo 填配置

本例假设客户服务器内网 IP 为 192.168.10.20，MySQL、Redis、一体化平台后端都在这台服务器上，AgentOS 用 Docker 运行；用户通过 https://office.example.com 访问平台。IP 和域名均为示例，请换成自己的真实值，域名应已配置 DNS、证书及平台入口。

cd /opt/agentos-src
node tools/setup.mjs init --mode deploy

编辑 deploy/agentos.env，用下面内容替换同名行，不是追加或覆盖整份文件：

MYSQL_URL=jdbc:mysql://192.168.10.20:3306/ruoyi_office_agentos?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
MYSQL_USERNAME=agentos
MYSQL_PASSWORD=<replace-with-your-agentos-db-password>
REDIS_HOST=192.168.10.20
REDIS_PORT=6379
REDIS_DATABASE=5
REDIS_PASSWORD=<replace-with-your-redis-password>

AGENTOS_MAINLINE_URL=http://192.168.10.20:48080
AGENTOS_MAINLINE_WEB_URL=https://office.example.com
AGENTOS_WEB_URL=https://office.example.com/ai/
AGENTOS_TENANT_ID=1
AGENTOS_ADMIN_ROLE_ID=1

例如你的服务器是 192.168.10.35，就替换上面三个 192.168.10.20；平台后端实际端口为 48081，就改后端地址中的端口；平台入口域名为 oa.example.org，同时替换两处浏览器域名，智能体保留 /ai/。

先建独立空库 ruoyi_office_agentos 和独立账号 agentos，填真实强密码；不要使用本地教程的演示密码。Redis 示例按有密码配置，没有密码时写 REDIS_PASSWORD=，但必须确保网络隔离和访问控制。租户、管理员角色 1 只是示例，必须核对平台实际 ID。数据库跨不可信网络时应按客户安全要求启用 TLS，本例只说明受控内网地址。

为什么同一台服务器还不能填 127.0.0.1？ AgentOS 在容器内，127.0.0.1 指向容器自己，不是宿主机。这里使用宿主机的可达内网 IP；MySQL、Redis、平台后端应监听允许容器访问的接口，数据库账号和防火墙允许实际容器来源，禁止直接向公网开放中间件。浏览器的两个地址则必须是员工能访问的域名。

选择 GPT 或 DeepSeek

GPT 示例：

AGENTOS_MODEL_URL=https://api.openai.com
AGENTOS_MODEL_KEY=<replace-with-your-openai-api-key>
AGENTOS_MODEL=gpt-4.1-mini

DeepSeek 示例：

AGENTOS_MODEL_URL=https://api.deepseek.com
AGENTOS_MODEL_KEY=<replace-with-your-deepseek-api-key>
AGENTOS_MODEL=deepseek-flash

只选一套替换三个同名字段，Key 换成本人的服务商 API Key，尖括号也删除；默认接口路径由项目拼接，不在根地址后再加 /v1。服务商账户需有额度和模型权限，容器需能访问接口。

两套是配置示例，未使用真实 Key 联调；DeepSeek 当前思考模式的连续工具调用兼容性需要单独验收。详见本地教程的模型示例。生产标准路径与平台前端同域、固定 /ai/，分域部署不属于本快速路径。

保留自动生成的内部密钥，先检查再继续

AGENTOS_CLIENT_ID=agentos 保持不变；AGENTOS_CLIENT_SECRET、AGENTOS_ENCRYPT_KEY 保留 init 随机生成值，不是模型 Key。备份并长期保留，已有安装不能重新生成后直接使用旧密文。已有配置不会覆盖。

node tools/setup.mjs check --mode deploy

预期提示配置检查通过，然后继续第 3 节；检查不连接数据库、模型或平台。源码部署保留默认 local 镜像标签；交付镜像部署按第 5 节替换实际镜像。

KEY=value 可用单引号包裹空格，不支持内嵌单引号、双引号、换行和 ${...} 插值。不要 source 原始 env，也不要把密钥写入源码、截图或日志。 OCR/ASR 不用则留空，实验库 root 密码无需填写。

3. 生成配置、装配工程

源码构建：

node tools/setup.mjs prepare --mode deploy --platform /opt/ruoyi-office-src

使用预制交付镜像则无需本机平台源码，省略 --platform：

node tools/setup.mjs prepare --mode deploy

工具生成 agentos.properties、deploy/agentos.runtime.env、前端生产模式配置与 sql/generated。只生成文件，不会自动执行 SQL。 原始 env 是唯一配置源；每次修改后重新 prepare。runtime.env 正确保留密码中的 $ 等字符，供 Compose 使用，不要手改。 旧 apps-web-agentos/.env.local 会触发报错，先备份移出，避免把本地地址打入生产包。 私密文件被 Git 忽略，Linux 权限 600；Windows 需限制目录 ACL。

4. 首次空库安装与平台接入

由 DBA 创建独立 AgentOS Schema 和账号，安装期间授予建表/变更所需权限，运行期收敛到最小权限。 按顺序审核执行，失败即停止：

顺序	文件	执行库
1	sql/install/agentos/V1.0.0__agentos_baseline.sql	空 AgentOS 库
2	sql/generated/02_customer_seed.sql	AgentOS 库
3	sql/generated/03_record.sql	前两步成功后的 AgentOS 库
4	sql/generated/04_mainline.sql	经平台 DBA 确认的平台业务库

第二步清除金蝶模拟连接，调整基线种子租户归属；第三步记录原基线 SHA-256。保留历史交付基线不修改。 已有库禁止重跑此流程，应按版本增量升级。 平台集成脚本会更新已有 agentos OAuth 客户端，不能当作无影响的重复操作。

回调为 https://office.example.com/ai/sso-callback，授权方式含 authorization_code。菜单 /ai/work、/ai/dev，普通员工只授工作台，模型维护权限单独授管理员。 generated SQL 包含 OAuth 密钥，禁止提交 Git；每次 prepare 会刷新，已执行文件及执行记录另行安全留档。

5. 选择源码部署或镜像部署

A. 源码部署：无需自建镜像仓库

在平台后端目录编译：

cd /opt/ruoyi-office-src
mvn -Paddons -pl yudao-server-agentos -am -DskipTests package

产物应出现在 AgentOS 的 yudao-server-agentos/target/yudao-server-agentos.jar。 不要把 AgentOS 依赖加入平台默认 yudao-server。镜像标签默认 agentos-server:local、agentos-web:local，可改成版本号。

cd /opt/agentos-src/deploy
bash install.sh --source

脚本重新校验配置，构建镜像、启动并等待健康检查。 前端 Docker 构建使用锁文件，不包含 .env.local、.env.*.local、node_modules、dist；标准生产同域 /ai/，不会带入开发地址。 后端 Docker 上下文仅接收编译后的 JAR，私密配置不打进 JAR。

B. 预制交付镜像

将 AGENTOS_SERVER_IMAGE、AGENTOS_WEB_IMAGE 改为实际可拉取的固定版本或摘要，必要时先 docker login：

cd /opt/agentos-src/deploy
bash install.sh --images

默认 local 标签不是远程交付镜像；没有交付镜像请选择 A，不要直接 pull local 标签。

6. Nginx、日志和健康检查

将 deploy/nginx-agentos.conf 合并进平台现有 HTTPS server。 /ai/ 代理至 127.0.0.1:18080，/admin-api/agentos/ 至 127.0.0.1:48091，其他 API 保持平台代理。 专用 ^~ location 关闭 SSE 缓冲，读取超时至少 600 秒；CDN/Ingress 同样配置。 如果修改宿主端口，同步 Nginx upstream。

sudo nginx -t
sudo systemctl reload nginx
docker compose --env-file agentos.runtime.env ps
docker compose --env-file agentos.runtime.env logs --tail=200 agentos-server
bash health-check.sh

health-check 默认检查 18080，改端口则传入实际 http://127.0.0.1:端口。 日志使用命名卷，容器非 root 用户可写。不要执行 docker compose down -v 删除生产卷。 健康检查仅代表 Web 与服务端口可达，不代表模型/SSO/业务验收通过。

7. 基础验收与可选功能

依次验证：

1. 平台菜单一次跳转进入 AgentOS，用户和租户正确。
2. 普通对话流式输出，使用配置中的默认模型即可，不需要在模型页面重复录入。
3. 只读业务查询遵循当前员工权限，普通员工不能维护模型密钥。
4. 写操作先确认，取消后业务零写入。
5. 附件上传/预览/下载成功，返回的文件地址不含研发机 localhost。
6. 重启后会话仍在，页面模型密钥可解密。
7. 备份与恢复演练通过。

管理员在“开发 → 接入 → 模型服务”配置的租户模型优先；未配置则回落到默认模型。 OCR/ASR 按需配置再验收，OCR 需要匹配专用协议并配置文件域名白名单，不是填任意大模型 URL 即可识票。 Finance/HRM 可选 SQL 核对已购模块、前置检查、实际租户后执行，不属于全客户必跑。

实验中间件已拆入 compose.lab.yaml，仅实验时显式叠加 -f compose.yaml -f compose.lab.yaml。 使用 mysql-lab/redis-lab 服务名、填写 root 密码，先启动中间件并初始化数据库；生产不要使用这一方案。

8. 配置变更、升级和回滚

修改源配置后 prepare，再重建容器；只编辑 env 不会自动生效。 升级前备份数据库与配置，保留原密钥，按发布说明执行增量 SQL，禁止重跑基线。

cd /opt/agentos-src/deploy
bash backup.sh
# 修改交付镜像版本后
bash upgrade.sh

源码部署升级先重新编译后端，再 install.sh --source。镜像升级走 upgrade.sh。 回滚设置 AGENTOS_SERVER_IMAGE_PREVIOUS、AGENTOS_WEB_IMAGE_PREVIOUS 后执行 bash rollback.sh。 数据库有不兼容变更需按发布说明回滚，不能只换镜像；回滚后同步配置源镜像版本。

9. 排错顺序与安全

先运行 node tools/setup.mjs check --mode deploy，再查容器日志，不打印带密钥的 Compose 完整配置。 依次检查占位符、容器网络、数据库初始化、OAuth/角色、模型、SSE/附件。 配置校验不等于外部服务连通，上线必须完成第 7 节验收。历史已暴露凭据应轮换失效，当前文件删除不能消除 Git 历史泄漏。