部署与初始化配置

给实施和运维人员。按本篇做完，员工就能从业务系统一键进入智能体。可选项（语音、备用模型、外部资讯、机器人入口、授权书）见 实施附录。

部署形态

智能体是独立加装的一层：独立进程、独立数据库，通过业务系统现有接口工作。业务系统不用改代码，也不用停机。

三条原则：

1. 身份来自业务系统：智能体不建用户表，员工的账号、部门、角色全部沿用业务系统。
2. 数据分库：对话、留痕、能力注册表、知识库都在智能体自己的库里，不写业务系统库。
3. 代员工调用：智能体查业务数据时带的是这名员工自己的令牌，业务系统该拒绝的照样拒绝。

一、准备

项	要求
业务系统	RuoYi Office 已部署并可访问
JDK	17，与业务系统一致
MySQL	5.7 或 8.x，新建一个空库给智能体
Redis	可以和业务系统共用实例，但要用不同的 database 编号
大模型	任一 OpenAI 兼容协议的服务：云端 API 或内网自建推理服务都可以
交付包	智能体服务 jar、前端静态文件、初始化 SQL、配置样例

二、初始化数据库

交付包里的 SQL 按文件名序号执行。文件名里带「主线」的打业务系统库，带「独立库」的打智能体库：

1. 新建智能体库（字符集 utf8mb4）。
2. 按序号执行全部脚本。
3. 业务系统库这几步会做三件事：
   • 注册智能体这个 OAuth2 客户端，用于互相免登录；
   • 在业务系统菜单里加「企业管理智能体」入口（工作台、智能体开发）；
   • 给超级管理员角色授上入口菜单。

要注意什么：

• 个别脚本是加字段的变更，重复执行会提示字段已存在，属于正常情况，不要当失败处理。
• 打完业务系统库的菜单、按钮脚本后，要清掉业务系统缓存里的菜单列表（Redis 键 menu_list:*），或重启业务系统服务。否则新加的按钮权限（如「维护模型」）在缓存过期前不生效，超级管理员也会看到只读页面。

三、部署智能体服务

智能体服务是一个独立 jar，不要合并进业务系统的服务里。按交付包里的配置样例写 application-prod.yaml，至少配这几项：

spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://<库地址>/<智能体库>?useSSL=false&serverTimezone=Asia/Shanghai
          username: <账号>
          password: <密码>
  data:
    redis:
      host: <redis 地址>
      database: <与业务系统错开的编号>

yudao:
  agentos:
    mainline:
      base-url: http://<业务系统服务内网地址>   # 内网直连，不要绕公网
      client-id: agentos
      client-secret: <与业务系统 OAuth2 客户端里的密钥一致>
    playground:
      enable: false   # 联调页，生产必须关闭

mybatis-plus:
  encryptor:
    password: ${AGENTOS_ENCRYPT_KEY}   # 模型密钥加密存库用，必须 16 位

启动：

java -jar yudao-server-agentos.jar --spring.profiles.active=prod

要注意什么：

• 密钥、密码只写在服务器上的配置文件或环境变量里，不要提交到代码仓库。
• AGENTOS_ENCRYPT_KEY 每个客户单独生成一个 16 位随机串，上线后不要再改：改了以后，页面上已经录入的模型密钥都解不开，要重新录一遍。
• 生产必须用 prod 配置启动。其他配置下，框架会把请求参数原样打进运行日志，保存模型时的密钥也在其中。
• 智能体服务要能访问业务系统服务和大模型服务；员工浏览器不需要直接访问它们。

四、连接大模型

日常的模型都在页面上维护：「开发 → 接入 → 模型服务」，按单位、按用途（对话、语音转写、OCR 识别）分别配，保存后立即生效，不用重启，做法见 管理员篇。

配置文件里只放兜底模型：某个单位的某种用途在页面上一条都没配时，才用配置文件里的。老部署升级后不配页面，行为和以前一样。对话兜底模型用 OpenAI 兼容协议，云端和内网写法一样：

spring:
  ai:
    openai:
      api-key: ${AGENTOS_MODEL_KEY}
      base-url: ${AGENTOS_MODEL_URL}
      chat:
        options:
          model: ${AGENTOS_MODEL}

• 要求数据不出内网的客户，把 base-url 指向内网自建推理服务即可，不用改代码。
• 某个单位在页面上配了对话模型以后，这个单位就只按页面上的顺序走，配置文件里的对话模型不再参与。
• 换模型供应商优先在页面上改；改配置文件要重启。
• 失控防护默认开启（单轮步数、会话轮次、输入长度上限），不建议关闭：模型反复查同一个接口是常见情况，没有这道闸门，一次死循环就可能用掉大量额度。
• 模型限流较多时，在模型服务页面的对话页签再加一条排在后面作为备用，见 实施附录。

怎么验证：员工在工作台问一句「只回复两个字：收到」，能答出正文即连通。看到「智能体当前使用的人比较多，请稍等片刻再试」说明连上了但模型繁忙；如果一直如此，检查模型账号的额度和并发限制。

五、部署前端并与业务系统同域

前端静态文件放在业务系统同一个域名的 /agentos/ 路径下。反向代理示例（nginx）：

location /agentos/ {
    alias /data/ruoyi-office/agentos-web/;
    try_files $uri $uri/ /agentos/index.html;
}

location /admin-api/agentos/ {
    proxy_pass http://<智能体服务内网地址>/admin-api/agentos/;
    proxy_set_header Authorization $http_authorization;
    proxy_set_header tenant-id $http_tenant_id;
    proxy_http_version 1.1;
    proxy_buffering off;      # 对话是流式返回，必须关缓冲
    proxy_cache off;
    proxy_read_timeout 300s;
}

其余 /admin-api/ 仍然指向业务系统服务，不用改。

要注意什么：

• proxy_buffering off 必须加，否则回答会憋到最后一次性出现。
• 业务系统和智能体分别用不同域名部署时，构建前端前要把业务系统地址写进前端环境变量 VITE_MAINLINE_WEB_URL；同域部署留空即可。

六、打通业务系统登录

员工已登录业务系统时打开智能体，会走业务系统的 OAuth2 授权码自动登录，不再输密码。要让它生效：

1. 在业务系统「系统管理 → OAuth2 客户端」里找到 agentos 客户端。
2. 「授权类型」包含授权码、刷新令牌。
3. 「可重定向的 URI 地址」加上客户自己的智能体地址，例如 https://<客户域名>/agentos（按前缀匹配）。
4. 「自动授权范围」勾上 user.read、user.write，员工就不会看到授权确认页。
5. 客户端密钥与智能体服务配置里的 client-secret 保持一致。

怎么验证：在业务系统登录后，新开标签打开 https://<客户域名>/agentos/work。

• 第一次打开、公司有多个单位时，会先让员工选「所在单位」，点「使用业务系统账号登录」后自动回到工作台；
• 之后再打开直接进入。

要注意什么：回调地址没加白名单时，业务系统会拒绝回跳；智能体在同一会话里不会反复自动跳，员工可以在登录页改用账号密码登录。

七、改业务系统菜单的入口地址

初始化脚本里的菜单入口是示例地址。到业务系统「系统管理 → 菜单管理」，把「企业管理智能体」下两个外链菜单改成客户自己的地址：

菜单	地址
智能体工作台	https://<客户域名>/agentos/work
智能体开发	https://<客户域名>/agentos/dev

指定智能体管理员

「开发」栏只给智能体管理员。在业务系统里，有以下任一权限的员工就是智能体管理员：

• 超级管理员；
• 菜单「智能体开发」（权限标识 agentos:admin）及其下的按钮：安装技能、维护智能体、审核能力、维护模型。

做法：在业务系统「角色管理」里新建一个「智能体管理员」角色，勾上「企业管理智能体」下的菜单和按钮，分配给负责人。普通员工的角色只勾「智能体工作台」即可。

「维护模型」（agentos:model:update）单独管模型的增删改、排序、启停和从业务系统同步。模型密钥直接关系到费用，建议只给一两个负责人。没有这个按钮的智能体管理员能查看模型和点自测，不能改。

八、首次配置清单

部署完成后，管理员按顺序做一遍：

步骤	在哪里	做什么
1	开发 → 接入 → 模型服务	配对话主模型和备用模型；用到语音输入、发票识别时再配语音转写和 OCR；逐条点「自测」
2	开发 → 能力审核	上架首批只读能力：待办、已办、我的流程、假期余额等
3	开发 → 技能开发	确认预置技能已安装（审批办理、人事查询、周报素材、企业问答、费用报销）
4	开发 → 智能体开发	确认预置智能体已启用，按需调整提示词
5	工作 → 知识库	灌入公司制度原文，用员工的问法做召回验证
6	开发 → 管理空间授权	给总经理、财务负责人授权对应空间
7	开发 → 授权与运营	导入授权书后核对席位与到期日，见 实施附录

九、验收

检查项	怎么做	期望
免登录	业务系统登录后打开智能体地址	不输密码直接进入工作台
模型连通	工作台问一句话	答出正文；繁忙时只出现友好提示，不出现报错原文
本人权限	用普通员工问「我还有哪些待办」	只列出他本人的待办
权限边界	普通员工登录	看不到「管理」「开发」；手输地址会被送回工作台
不代批	问「帮我把第一条待办批了」	明确拒绝，引导到业务系统待办页亲自处理
写操作确认	让它新建一张单据	先出确认卡片，确认后才提交
知识库	灌一份制度后用员工问法提问	按原文回答并带出处
管理空间	授权的管理者打开今日摘要	指标有值或显示「暂未取到」，不编数

日常运维

• 留痕：每次执行和每一步调用（入参、出参、耗时、成败）都有记录。客户质疑「这个数字哪来的」时，按执行记录就能查到调了哪个接口、传了什么。
• 清理：每一步的调用明细增长最快，可以按保留期清理；按天的用量汇总要长期保留，续费核对要用。
• 能力上下架：新登记的能力默认待审，人工核对风险等级和数据范围后才上架。