企业官网建设流程全解析

Routa 是一个 Workspace 优先（Workspace-first）的 AI 多 Agent 协作平台，支持共享 Spec、Kanban 看板编排，以及 MCP / ACP / A2A 协议，同时覆盖 Web 与桌面端。想让团队共享一个 Routa 实例？通过 Docker Compose 一键搭建是最快的路径——无需本地安装 Node 环境，一条命令即可在服务器或本机拉起服务，几分钟后就能通过浏览器访问完整的看板与多 Agent 会话界面。

本文面向新手和普通用户，带你完成 Routa 自部署的完整流程。

一、Routa 自部署前的准备工作

部署开始前，确认你的机器满足以下条件：

Routa 仓库中已内置完整的容器化部署文件，核心只有两个：

• docker-compose.yml：服务编排文件，定义了应用、数据库、迁移三个服务
• Dockerfile：多阶段构建，基于node:22-alpine，最终运行一个精简的 standalone 生产镜像

值得留意的是，Dockerfile 还特意在镜像里安装了git和ca-certificates，因为 Web 端的仓库克隆功能（/api/clone接口）依赖容器内的git clone/git pull，所以你部署后可以直接在界面里克隆远程仓库。

二、获取代码并一键启动（SQLite 默认模式）

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/ro/routa cd routa

第 2 步：启动服务

docker compose up -d --build

就这么简单。docker-compose.yml 中的默认配置使用SQLite 数据库（ROUTA_DB_DRIVER=sqlite），数据存放在容器内/app/data/routa.db，并挂载到名为routa_data的 Docker 卷中——不需要任何外部数据库。

第 3 步：验证服务健康

Compose 文件已内置健康检查，你可以随时查看服务状态：

docker compose ps curl http://localhost:3000/api/health

看到{"status":"ok","timestamp":"..."}的响应（对应实现见 src/app/api/health/route.ts），就说明 Routa 已成功运行。

三、生产级部署：启用 PostgreSQL 数据库

SQLite 模式适合小团队和快速试用。如果是多用户的团队级部署，建议启用随 Compose 文件捆绑的 PostgreSQL 16：

docker compose --profile postgres up -d --build

这会在 docker-compose.yml 中额外启动两个服务：

• migrate：一次性容器，启动前自动执行数据库结构同步（db:push）
• postgres：postgres:16-alpine，带健康检查，数据落在postgres_data卷中

生产环境必改项——创建.env文件修改数据库密码（默认密码是routa_secret，见 docker-compose.yml）：

POSTGRES_PASSWORD=你的强密码

如果你的团队已有外部 PostgreSQL 实例，也可以直接指定连接串，跳过捆绑的数据库：

DATABASE_URL=postgresql://用户:密码@你的主机:5432/库名 ROUTA_DB_DRIVER=postgres

💡 小贴士：应用服务带有restart: unless-stopped策略，服务器重启后服务会自动恢复。

四、部署完成后：打开界面，创建团队工作区

启动成功后，浏览器访问http://localhost:3000，你会看到 Routa 的 Kanban 看板界面——这就是团队共享任务与 Agent 编排的核心面板：

看板上可以直观看到每张任务卡片的执行状态、负责该任务的 Agent 角色（如 CRAFTER、CRAFT 等）以及所使用的 Provider。顶部还显示了 Kanban 健康度、运行中/排队中的会话数，方便团队随时掌握整体进度。

部署后建议按以下顺序完成首次配置（更多细节参考 快速开始文档）：

1. 创建 Workspace：工作区是 Routa 的核心组织单元，团队共享同一个工作区
2. 启用一个 Provider：进入Providers配置一个可用的 AI 提供方即可，不需要全部配置
3. 挂载仓库：关联团队代码仓库（支持界面内直接克隆远程仓库）
4. 启动 Session：从一次简单的会话开始，例如让 Agent 解释仓库架构，确认链路完全打通

五、配置 AI Provider：环境变量与界面两种方式

Routa 支持多种 AI 提供方接入，团队部署时最常用的方式是在容器里注入 API Key。修改 docker-compose.yml 中app服务的environment段，添加你使用的变量即可：

完整变量说明可参考 环境变量文档 和 提供方与模型文档。

官方建议很实际：只配置你实际使用的提供方，一个可用的 Provider 就足够跑起来。你也可以不碰环境变量，直接在 Web 界面的Providers页面填写凭据——两种方式等效。

六、会话追踪：确认多 Agent 在协同工作

会话跑起来后，左侧的 Traces 入口是验证部署质量的最好方式——它可以浏览和分析所有 Agent 执行轨迹：

左侧列出全部历史会话（图中示例已有 433 个），点击任意会话可以展开完整时间线：用户指令、Agent 的每一次工具调用（Bash、Read、Edit、MCP 工具等）都清晰可查。对于团队管理者来说，这是排查 Agent 行为、审计执行过程的关键面板。

七、数据持久化与日常运维速查

数据都存在哪里？

• SQLite 模式：routa_data卷（容器内/app/data/routa.db）
• PostgreSQL 模式：postgres_data卷

常用运维命令：

# 查看服务状态 docker compose ps # 查看应用日志 docker compose logs -f app # 升级：拉取新代码后重建 git pull && docker compose up -d --build

常见问题速查

总结：三步完成团队级部署

回顾一下整个流程，Routa 的自部署其实只有三步：

1. git clone+docker compose up -d --build（SQLite 模式，最快路径）
2. 需要生产级数据库时加--profile postgres，并在.env中修改密码
3. 浏览器访问http://localhost:3000，创建 Workspace、配置 Provider、挂载仓库

至此，一个团队共享的 AI 多 Agent 协作平台就上线了：看板驱动任务编排，Spec 保持上下文共享，MCP / ACP / A2A 协议支撑 Agent 间通信。更多使用方式可以参考 使用 Routa 文档 和 自托管文档，把团队真正带入 AI 协作时代。