本地启动与调试

目标：客户取得配套源码后，只填写中间件、大模型、一体化平台三组配置，即可开始启动。无需 License、公钥、体验码；OCR、ASR 按需启用。

LOCAL DEVELOPMENT

本地四进程联调

两套前端 · 两套后端 · 身份统一

员工浏览器

↓

前端开发服务

AI WORKSPACEAgentOS 前端localhost:5666

BUSINESS WEBRuoYi Office 前端localhost:5800

/admin-api/agentos/**↓ 对话与能力登录 / 租户 / 文件↓ 平台业务

Java 服务

SLIM SERVERAgentOS 后端127.0.0.1:48091

BUSINESS SERVERRuoYi Office 后端127.0.0.1:48080

当前员工 Token / OAuth2 →

AgentOS 独立 MySQLRedis 独立 DB大模型 APIOCR / ASR 按需

1. 环境与源码

准备 JDK 17、Maven 3.9+、Node.js 22.12+、pnpm 10.33.0、MySQL 8、Redis 6/7。必须取得兼容版本的平台后端、平台 PC 前端及 AgentOS；AgentOS 编译复用平台框架，不是单仓独立编译工程。

推荐目录：

workspace/
├── ruoyi-office/          平台后端
├── ruoyi-office-vben/     平台前端
└── ruoyi-office-addon/
    └── agentos/           智能体

先按平台文档完成初始化，确认平台后端 48080、前端 5800 能正常登录。另建一个空的 AgentOS Schema 与独立账号；Redis 可以共用实例但使用独立 database。不要把平台数据库账号交给 AgentOS。

2. 照着本机 Demo 填配置

下面假设你在同一台电脑运行 MySQL、Redis、一体化平台和 AgentOS（JAR/IDE，不是 Docker），先选 GPT 或 DeepSeek 中的一套跑通。

2.1 先对照你的本机环境

服务	本文 Demo 的实际值	你需要确认
AgentOS 数据库	127.0.0.1:3306/ruoyi_office_agentos	先用数据库客户端创建这个空库
数据库账号	agentos / LocalDemo_Only_2026	独立用户已创建并有该库权限；这是假设的本地演示密码
Redis	127.0.0.1:6379，database 5，无密码	实例已启动，database 5 可用且未被其他应用占用
平台后端	http://127.0.0.1:48080	一体化平台后端已启动
平台前端	http://localhost:5800	能用平台账号正常登录
AgentOS 前端	http://localhost:5666/	后续启动前端后使用，不带 /ai/
平台租户 / 管理员角色	1 / 1	从平台租户、角色管理核对实际 ID，不是登录用户 ID

填配置不会自动创建 MySQL 账号或数据库，也不会替你启动平台。 如果你现有数据库密码不是示例密码，直接填现有独立账号的真实密码，不要为了照抄去修改共享数据库账号。

在 AgentOS 仓库根目录执行（PowerShell、Linux/macOS 相同）：

node tools/setup.mjs init --mode local

用编辑器打开生成的 deploy/agentos.env。已有文件时跳过 init，直接编辑，不要删除旧配置重新生成密钥。

2.2 填入本地中间件和平台地址

在文件中找到下列同名行并替换。不是把整块追加到末尾，也不是覆盖整个文件；重复键会校验失败。

MYSQL_URL=jdbc:mysql://127.0.0.1:3306/ruoyi_office_agentos?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
MYSQL_USERNAME=agentos
MYSQL_PASSWORD=LocalDemo_Only_2026
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DATABASE=5
REDIS_PASSWORD=

AGENTOS_MAINLINE_URL=http://127.0.0.1:48080
AGENTOS_MAINLINE_WEB_URL=http://localhost:5800
AGENTOS_WEB_URL=http://localhost:5666/
AGENTOS_TENANT_ID=1
AGENTOS_ADMIN_ROLE_ID=1

例如 MySQL 实际端口是 3307，就把 JDBC 地址中的 :3306/ 改成 :3307/；Redis 有密码，就填 REDIS_PASSWORD，无密码保留空值。平台前端端口不同只改对应前端地址，不要把它填进后端地址。浏览器全程使用 localhost，不要中途混用 127.0.0.1 登录。

2.3 大模型选一套，替换三个同名字段

方案 A：GPT（OpenAI 官方接口）

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

将第二行整个占位值（含尖括号）换成你在 OpenAI API 平台创建的真实 Key；不要填 ChatGPT 登录密码。示例选用支持 Chat Completions 和工具调用的 GPT-4.1 mini，不要求追最新型号。

方案 B：DeepSeek（官方接口配置示例）

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

第二行换成 DeepSeek 开放平台的真实 Key；不能沿用 OpenAI Key。模型名按当前官方文档示例填写，账户可用模型以服务商为准。

两套配置只能保留一套，不是自动主备；以后切换时同时替换 URL、Key、模型名，再 prepare 并重启后端。示例 Key 都是无效占位符，校验工具会提醒替换。API 账户需开通相应模型、有可用额度，运行 AgentOS 的机器需能访问服务商。

本项目默认在 URL 后拼接 /v1/chat/completions，这里填服务根地址，不要再手动追加 /v1 或完整接口路径。第三方网关的路径规则可能不同，不能只替换 Key 就假设兼容。

验证边界：这两套是填写示例，不代表已完成真实 Key 联调。 DeepSeek 当前默认思考模式对工具调用历史有额外要求；上线前必须验收流式对话及连续业务工具调用，配置检查通过不等于模型兼容性通过。遇到 reasoning_content 等 400 错误，应核对适配层和服务商要求，不能靠反复换 Key 解决。

模型名与接口参考：GPT-4.1 mini 官方说明、DeepSeek 官方说明。

仓库还提供可直接打开对照的填写片段：deploy/examples/local-gpt.env.example、deploy/examples/local-deepseek.env.example。内容对应上述本机环境；它们不会被自动加载，应将选中片段的同名行替换到 deploy/agentos.env。

2.4 哪些不用改，怎样知道填对了

AGENTOS_CLIENT_ID=agentos 保持不变。AGENTOS_CLIENT_SECRET 和 AGENTOS_ENCRYPT_KEY 已由 init 随机生成，保留生成值，不要填成模型 Key，也不要照抄别人的内部密钥。镜像、宿主端口等其他行先保留默认值；本地后端默认端口为 48091。无需配置 License、体验码、OCR 或 ASR。

node tools/setup.mjs check --mode local

预期提示：配置检查通过（未连接数据库、模型或平台）。 然后继续第 3 节生成文件，此时还没有启动服务。

OAuth Secret 和 16 位落库加密密钥应备份并长期保留，升级不重新生成；无需另跑 generate-secrets.sh。 语法为 KEY=value，含空格可用单引号包裹；不使用双引号、内嵌单引号、换行和 ${...} 插值。不要 source 配置或把密钥提交 Git。Linux 文件权限 600；Windows 限制配置目录 ACL。

3. 生成运行配置并装配工程

node tools/setup.mjs prepare --mode local --platform ../../ruoyi-office

非标准目录把 --platform 改为平台后端实际路径。脚本将校验配置、挂载两个 AgentOS 后端模块并生成：

• 根目录 agentos.properties：Spring Boot 的运行配置，不打入 JAR。
• apps-web-agentos/.env.development.local：仅开发模式的前端地址，不含后端密钥。
• deploy/agentos.runtime.env：部署工具使用的生成文件。
• sql/generated/：待审核的初始化 SQL，不自动执行、不连接数据库。

修改配置源后重新 prepare，不要改生成文件。已有其他源码占用模块目录时脚本报错，不覆盖。 旧工程已有 apps-web-agentos/.env.local 时，请先备份并移出，再将必要配置合并到统一入口，防止开发地址进入生产包。 不要再往 resources 放真实 application-local.yaml；旧运行配置的同名环境变量也应清理。

仅校验、不写入：

node tools/setup.mjs check --mode local

4. 首次初始化数据库

使用数据库客户端按顺序执行，任一步失败即停止：

顺序	文件	执行库
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	平台管理员审核后，在平台库执行

第二步移除金蝶模拟连接，并按配置调整初始化种子的租户归属。第三步记录原始基线校验和。这是首次空库安装流程，禁止用于已有库升级。

第四步配置 OAuth、菜单和管理员权限，含客户端密钥，禁止提交 Git；会更新平台已有 agentos 客户端，已有安装不要重跑。回调应允许 http://localhost:5666/sso-callback，授权方式含 authorization_code。 prepare 会刷新 generated 文件，已执行的 SQL、校验和与执行记录应另行安全留档。

5. 编译与启动后端

在平台后端目录：

mvn -Paddons -pl yudao-server-agentos -am -DskipTests package

然后回到 AgentOS 仓库根目录：

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

本地也使用 prod profile，它表示统一参数配置，不表示连接线上。实际地址来自根目录 agentos.properties。 默认后端端口 48091，日志 logs/agentos.log。工作目录错误会读不到配置；环境变量优先于文件，排除旧配置覆盖。

IDEA 运行设置：

• 重新加载 Maven，编译 AgentOS 时启用 addons；不要将依赖加入平台默认 yudao-server。
• Main class：cn.iocoder.yudao.server.YudaoAgentosServerApplication。
• Working directory：AgentOS 仓库根目录，不是平台后端目录。
• Active profiles：prod。不必重复填一批环境变量。
• 平台仍按自己的运行配置启动，与 AgentOS 独立运行。

6. 启动前端并验收

平台前端按其文档运行 pnpm dev:antd。AgentOS 前端：

cd apps-web-agentos
pnpm install --frozen-lockfile
pnpm dev

先登录 http://localhost:5800，再打开 http://localhost:5666/work。本地开发不带生产的 /ai/ 路径。

验收：一次 OAuth 跳转后用户/租户正确；普通消息有流式输出；只读查询符合员工权限；写操作先确认、取消不写入；附件上传/预览/下载正常；重启后会话和模型密钥仍可用。 配置中的默认模型即可对话，无需再到模型页面重复录入；页面主备模型属于进阶配置。

OCR、ASR、Finance/HRM 和第三方连接按需再配置，核对已购模块、前置检查和实际租户，不要默认执行所有可选 SQL。

7. 常见问题

现象	排查
父 POM 或模块缺失	核对配套版本，运行 prepare --platform；不要维护两份源码
缺 MYSQL_URL 等变量	确认工作目录、agentos.properties 和 prod profile
配置修改不生效	修改 env 后 prepare、重启，并清理旧环境变量
登录循环或 401/403	OAuth Secret、回调、实际租户和角色权限
默认模型 404	Spring AI 默认拼接 /v1/chat/completions，URL 不要重复追加路径
非默认租户没有初始能力	核对首次安装是否执行客户种子步骤，已有库不要盲目重跑
OCR 读不到附件	专用服务协议、Token、文件域名白名单和网络可达性
Maven 下载失败	检查交付版本、网络和 Maven settings，不能依赖研发机私有缓存

生产环境请按完整部署手册操作，不能把 localhost 开发配置直接用于容器。