如何将OpenTag部署到Railway：双服务生产架构完整教程-平芜编程栈

【免费下载链接】OpenTag

OpenTag: The Channels SDK starter application, a self-hosted AI on-call triage bot for Slack and Microsoft Teams, built with AG-UI and LangGraph. Fork it and ship your own.

项目地址：https://gitcode.com/gh_mirrors/open/OpenTag

点击查看免费下载

OpenTag 是一个可自托管的 Slack 和 Microsoft Teams AI 知识库工作机器人，基于 AG-UI 与 LangGraph 构建。本文将带你完成 OpenTag 部署到 Railway 平台的完整流程：理解它的 agent + runtime 双服务架构、配置环境变量、执行部署并验证上线，最终在聊天频道里拥有一个真正可用的 AI 助手。

一、先认识 OpenTag：部署前你需要知道什么

OpenTag 不是一个"单体应用"，而是由两个职责明确的服务组成。部署前理解这个边界，能避免绝大多数配置错误：

服务	语言	职责	端口	健康检查
`agent`	Python + LangGraph	AI 大脑：推理、工具调用、联网研究	8123	`/health`
`runtime`	Node.js + CopilotRuntime	频道接入层：连接 Slack/Teams、渲染原生 UI	3000	`/api/copilotkit/info`

消息流向是：Slack/Teams → CopilotKit Intelligence（托管连接）→runtime→ AG-UI 协议 →agent。runtime 通过 Railway 内网访问 agent，不需要任何公网隧道或 Socket Mode。

部署完成后，它会这样工作：

二、部署前准备：5 分钟清单 ✅

在动手之前，确认你已具备：

CopilotKit 账号：一个 Intelligence 项目和 API Key（INTELLIGENCE_API_KEY），免费方案即可
OpenAI API Key：agent服务必需
Slack 工作区：能安装应用，且已完成 Channel 创建（务必先创建 Channel 再建 Slack 应用，详见 README.md 的 Quick start）
Railway 账号：已连接你的代码仓库

⚠️ 一个关键提醒：Channel 名称是"认领制"的。如果你 fork 了 OpenTag，请给你的部署分配独立的 Intelligence 项目、API Key 和 Channel 名称，否则多个 runtime 会为同一条消息互相竞争投递。

三、OpenTag 部署步骤：Railway 双服务上线 🚀

1. 克隆仓库并检查依赖

git clone https://gitcode.com/gh_mirrors/open/OpenTag cd OpenTag pnpm install

2. 阅读部署拓扑定义文件

整个 Railway 拓扑以代码形式声明在.railway/railway.ts中，只有两个服务、约 100 行：

agent 服务：源目录agent/，启动命令uvicorn main:app --host "" --port ${PORT:-8123}，健康检查/health，失败重启最多 5 次
runtime 服务：仓库根目录，构建时执行pnpm exec playwright install chromium（富 UI 渲染需要 Chromium），启动命令pnpm runtime
内网联动：runtime 的AGENT_URL指向 agent 的 Railway 私有域名，跨服务通信不出公网

如果你想部署到自己的仓库或分支，只需修改该文件中的REPO和BRANCH常量。

3. 本地验证部署配置

部署前先在本地评估配置，确认两个服务的变量声明无误：

node node_modules/railway/dist/iac/bin.js

仓库自带一份针对这份部署图的契约测试 app/railway.test.ts，它会严格断言：每个服务携带哪些环境变量、健康检查超时（300 秒）、重启策略，甚至启动命令引用的脚本在 package.json 里真实存在。

4. 执行 Railway 部署

安装 Railway CLI 后执行：

railway init railway up

IaC 文件会自动在 Railway 上创建agent和runtime两个服务并触发构建。

5. 为每个服务配置环境变量

这是最容易出错的一步。两份服务的变量不是随便放的，设计逻辑是：凭证跟着用它的服务走。

agent 服务（必填）：

变量	说明
`OPENAI_API_KEY`	唯一必填项，模型访问凭证
`INTELLIGENCE_CHANNEL_NAME`	固定为`open-tag`，同时是共享工具的默认 user_id
`LINEAR_API_KEY`、`GITHUB_PERSONAL_ACCESS_TOKEN`等	可选，按需开启对应数据源

runtime 服务（必填）：

变量	说明
`INTELLIGENCE_API_KEY`	Intelligence 连接凭证
`AGENT_AUTH_HEADER`	与 agent 服务完全一致的共享密钥
`INTELLIGENCE_CHANNEL_NAME`	同样固定为`open-tag`

⚠️两个高频坑：

AGENT_AUTH_HEADER必须在两个服务上手动设置成相同的非空值——Railway 不会替你同步，不一致会导致所有 runtime 请求 agent 时返回 401
Slack 应用务必关闭 Socket Mode，并在 OAuth 页执行 Reinstall to Workspace，否则会出现"安装成功但收不到任何消息"的假象

完整的环境变量契约参考 setup.md 的 Railway 章节。

四、部署验证：三步确认真的上线了 🎯

服务全绿只是第一步，真正可用要过这三关（用真实人类账号发送）：

@机器人提问：@OpenTag what changed in the last deploy?—— 应收到有内容的回复
同线程不 @ 追问—— 应继续回复（@ 即订阅了该线程）
新对话不 @ 发消息—— 应该没有回复，若回复了说明触发规则配错了

最后把机器人拉进频道：/invite @OpenTag（Slack 不会向机器人不存在的频道发送 mention 事件）。

上传一份 CSV，它还会直接在 Slack 里渲染成原生图表并给出结论：

如果验证失败，按顺序排查：

npx --yes copilotkit@latest channels status --json LOG_LEVEL=debug pnpm runtime

更严格的验证方式是用仓库自带的 Slack 实时测试框架，说明见 e2e/README.md。

五、常见问题与故障速查

症状	原因	解法
Slack 装好了但毫无反应	Socket Mode 开着，或没 Reinstall	关掉 Socket Mode，Reinstall 并更新 Signing Secret
runtime 请求 agent 返回 401	两端`AGENT_AUTH_HEADER`不一致	两边设为相同非空值
收到"终端没见过的回复"	Channel 名称冲突，别处 runtime 抢走了投递	为部署分配独立的 Channel 名称
部署反复重启	启动命令与脚本对不上	参考 app/railway.test.ts 的断言核对
渲染图表/图片失败	runtime 缺少 Chromium 或系统库	确认`RAILPACK_DEPLOY_APT_PACKAGES`构建变量生效

六、延伸阅读

部署拓扑源码：.railway/railway.ts
完整环境变量契约与 Railway 说明：setup.md
运行时入口与生命周期：server.ts
环境默认值（如 Intelligence 端点）：app/env.ts
频道行为与触发规则：app/channel.tsx
协作开发约定：AGENTS.md
AWS 部署替代方案（ECS Fargate + Secrets Manager）：deployment/aws/README.md

双服务架构 + 声明式 IaC + 契约测试，让 OpenTag 的 Railway 部署既清晰又可审计。Fork 它，换上你自己的 agent 与工具，就能拥有专属的 AI 值班助手。

【免费下载链接】OpenTag

OpenTag: The Channels SDK starter application, a self-hosted AI on-call triage bot for Slack and Microsoft Teams, built with AG-UI and LangGraph. Fork it and ship your own.

项目地址：https://gitcode.com/gh_mirrors/open/OpenTag

点击查看免费下载