部署与兼容性

这个页面把 rauto-manager 从“概览”扩展为更适合企业运维团队的部署与集成文档。

部署模型

rauto-manager 是面向 rauto agent 集群的自托管控制平面。

典型生产部署形态：

一套中心化 manager
PostgreSQL 作为持久化数据库
多个分布在不同网络区域的 rauto agent
运维人员通过浏览器访问 manager

核心运行要求

必填：

PostgreSQL 数据库
DATABASE_URL
JWT_SECRET
AGENT_API_KEY

在更大规模部署中常用的可选项：

NEXT_PUBLIC_AGENT_API_KEY
NEXT_PUBLIC_MANAGER_URL
NEXT_PUBLIC_MANAGER_GRPC_URL
AGENT_TIMEOUT
AGENT_HEARTBEAT_INTERVAL
MANAGER_GRPC_ENABLED
MANAGER_GRPC_HOST
MANAGER_GRPC_PORT
MANAGER_GRPC_MAX_MESSAGE_BYTES

首次启动引导

首次启动时，/login 会跳转到 /setup 创建第一个管理员账号。

因此生产部署应关注：

首次流量前先完成数据库迁移
为 JWT_SECRET 生成安全随机值
严格管理 AGENT_API_KEY
控制首个管理员初始化窗口

标准自托管启动方式

npm install
cp .env.example .env
npx prisma migrate deploy
npm run dev

本地 schema 迭代时也可以使用：

npx prisma migrate dev

Vercel 部署说明

项目支持 Vercel 部署，并且已经包含 vercel.json 与 build:vercel 相关流程。

建议确认：

使用 PostgreSQL，例如 Neon
DATABASE_URL 指向已完成迁移的数据库
如果 Prisma 迁移需要直连串，设置 DIRECT_DATABASE_URL
提交 prisma/migrations/ 到仓库
Production 与 Preview 使用不同数据库或 branch
手动配置 JWT_SECRET 与 AGENT_API_KEY

重要限制

Vercel 不会启动内置的 manager gRPC 服务。

如果你要接入 gRPC Agent，必须在自托管 Node 环境运行 manager，并设置：

MANAGER_GRPC_ENABLED=true

演示环境

如果你想在自行部署前先查看 manager 界面，可以使用公开 demo：

地址：demo.rauto.top
用户名：admin
密码：123456

该 demo 仅用于演示和评估，请避免录入生产密钥、真实设备凭据或敏感 inventory 内容。

Agent 接入方式

HTTP 上报模式

适用于 manager 通过普通 Web 地址可访问的场景。

rauto agent \
  --bind 0.0.0.0 \
  --port 8123 \
  --manager-url http://<manager-host>:3000 \
  --report-mode http \
  --agent-name edge-sh-01 \
  --agent-token <same-agent-api-key>

gRPC 上报模式

适用于 manager 暴露了 gRPC listener 的自托管场景。

rauto agent \
  --bind 0.0.0.0 \
  --port 8123 \
  --manager-url http://<manager-host>:50051 \
  --report-mode grpc \
  --agent-name edge-sh-01 \
  --agent-token <same-agent-api-key>

Manager 对 Agent 的能力期望

注册成功后，manager 期望 agent 能提供：

注册与心跳更新
离线通知
设备清单全量同步
可达性增量更新
实时任务事件
任务结果回调
Agent 侧异步错误上报

HTTP 兼容性契约

如果使用 HTTP 上报，为了完整支持当前 UI，agent 至少应提供：

GET /api/connections
PUT /api/connections/{name}
POST /api/connection/test
GET /api/templates
GET /api/device-profiles/all
GET /api/device-profiles/{name}/modes
POST /api/devices/probe

这些接口支撑 manager 侧：

连接列表浏览
已保存连接同步与更新
连接测试
模板发现
profile 查询
设备探测与同步

gRPC 兼容性契约

如果使用 gRPC 上报，manager 期望 agent 在对应 task / reporting service 中提供至少这些能力：

任务下发
任务事件上报
任务结果回调
连接列表与保存
连接测试
模板列表
设备 profile 列表
profile mode 查询
设备探测与同步

rauto-manager 会根据已保存的 agent report mode 自动选择 HTTP 或 gRPC。

下发类型

当前 manager 支持这些任务类型：

类型	说明
`exec`	基于已保存连接下发单条命令
`template`	传入变量执行命名模板
`tx_block`	执行事务式命令块
`tx_workflow`	执行由 Agent 处理的工作流负载
`orchestrate`	提交多步骤编排计划

UI 对应关系：

普通任务弹窗：exec、template、tx_block
可视化设计器：tx_workflow、orchestrate

生产设计建议

在需要中心化控制时引入 manager

以下场景很适合 manager：

多个执行节点
共享 inventory
集中任务下发
全局实时执行可视化
中心化历史和通知

在 Agent 侧优先维护好 saved connections

很多 manager 的高级工作流依赖 agent 能稳定暴露或解析 saved connection。

明确选择 transport

以下场景更适合 HTTP：

部署更简单
只暴露 Web 端口更方便
使用 Vercel 或类似平台

以下场景更适合 gRPC：

manager 运行在自托管 Node 环境
更看重传输效率
希望 manager 侧控制链路都走 gRPC

常见部署问题排查

`The table public.Admin does not exist`

通常意味着：

prisma migrate deploy 没有成功执行
当前运行环境连接到了另一个未完成迁移的数据库或 branch

Agent 无法注册

重点检查：

manager 侧 AGENT_API_KEY 与 --agent-token 是否一致
manager URL 与端口是否正确
report mode 是否与实际监听方式一致
防火墙与网络路径是否允许访问

gRPC Agent 无法接入