QM 是一个为团队设计的多人 Agent 框架，部署方式比较特别：它不是一个“一键部署”的简单应用，而是一套需要你用自己的云账号来托管的组织级基础设施。官方推荐的方式是让 AI 编程助手（如 Claude Code、Codex）来帮你完成部署，而不是手动敲命令。

🎯 部署前置条件

QM 的部署假设你具备以下条件：

  • 云账号：一个 Fly.io 或 AWS 账号，所有资源都会部署在你自己的账号下。
  • Postgres 数据库：用于持久化会话、记忆等数据。
  • 基础设施知识：需要有人熟悉 Docker、云服务的基本操作。
  • Node.js 环境：推荐 Node.js >= 24.15.0 和 npm >= 11.10.0。

🚀 官方推荐部署流程：让 AI Agent 帮你部署

这是 QM 官方设计的核心路径。你不需要手动克隆仓库，qm init 会生成一套部署目录，并包含一个给 Agent 看的部署技能（Skill）。

第一步：在你的云账号下创建部署目录

找一个空目录，运行初始化命令。你需要选择 Fly.io 或 AWS 作为目标平台：

1
2
3
4
5
# 将 <slug> 替换为你的组织标识，<fly-or-aws> 选择目标平台
npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org <slug> --target <fly-or-aws>

npm install

这个命令会在当前目录生成 qm.config.jsonc、deployment.md 以及一个 .codex/skills/deploy-qm/ 目录。你不需要查看 QM 的源码仓库。

第二步：告诉你的 AI Agent 去部署

现在，把你常用的 AI 编程 Agent（Claude Code、Codex 等）的当前目录指向这个部署目录，然后给它一条指令：

“请按照当前目录下的 deployment.md 和 .codex/skills/deploy-qm/ 里的指导，帮我完成 QM 的部署。”

Agent 会读取这些文件，然后一步步引导你完成后续所有工作，包括：

  • 配置基础设施（确认云账号、计费信息）。
  • 设置 Web 登录方式（通常是通过邮箱发送一次性登录链接）。
  • 配置连接器（如 Slack、邮件等）。
  • 执行部署并运行实时检查（qm check --live）。

⚙️ 部署后管理

部署完成后，你可以使用 qm 命令行工具来管理你的实例：

1
2
3
4
5
6
7
8
# 查看状态
npm exec qm -- status

# 查看日志
npm exec qm -- logs

# 回滚到上一个版本
npm exec qm -- rollback

💡 如果不想用 AI Agent 部署

官方也提供了手动操作的 CLI 命令。流程大概是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 初始化（同上）
npm exec --yes --package=@yc-software/qm@latest -- qm init . --org <slug> --target aws

# 安装依赖
npm install

# 检查配置
npm exec qm -- check

# 验证外部环境（如云 CLI 是否登录）
npm exec qm -- doctor

# 渲染基础设施
npm exec qm -- infra render

# 预览部署计划
npm exec qm -- plan

# 执行部署（AWS 需要 --yes 确认）
npm exec qm -- up --yes

# 运行实时验证
npm exec qm -- check --live

不过，官方明确表示，用 Agent 来执行 deployment.md 里的流程是更可靠的方式，因为里面包含了大量需要根据你的环境动态调整的步骤。

📝 关于“私有分叉”的特别说明

如果你想让整个 QM 代码库和你自己的定制化修改放在一起管理，官方建议的做法是做一个私有的普通克隆（plain clone），而不是用 GitHub 的 “Fork” 按钮。因为 GitHub 的 Fork 会继承原仓库的可见性，无法将公开仓库的 Fork 设为私有。

1
2
3
4
5
6
7
8
# 先创建一个空的私有仓库 <org>/qm-private，然后执行：
git clone --bare git@github.com:yc-software/qm qm-seed.git
git -C qm-seed.git push --mirror git@github.com:<org>/qm-private
rm -rf qm-seed.git

# 克隆你自己的私有仓库来开发
git clone git@github.com:<org>/qm-private
git -C qm-private remote add upstream git@github.com:yc-software/qm

你的定制化内容都放在 deploy/layers/<org>/ 目录下，核心代码保持与上游一致，这样后续合并上游更新会容易很多。

由于 QM 的部署流程高度依赖你选择的云平台（Fly.io 还是 AWS）和具体的环境配置，如果你决定开始，可以告诉我你打算用哪个平台，我能帮你再看看有哪些细节需要提前准备。