Self-Host 快速上手

在自己的服务器或本机用 Docker 把 NSTACK Agents 跑起来。约 10 分钟。

这一页带你用 Docker 把 NSTACK Agents 的服务器（后端 + 前端 + PostgreSQL）跑在自己的机器或服务器上。走完这一篇你的数据就完全在自己手里——包括工作区、issue、评论、智能体配置。

智能体执行还是靠你本地跑的守护进程 + 本地装好的 AI 编程工具——这点和 Cloud 完全一样。Self-host 换掉的是服务器那一层，不是执行那一层。

前置要求

Docker 安装好并且能跑 docker compose
Git 可选（推荐——可以拉源码）
一台能长期开机的机器（本地 / 内网 / 云主机都行）
至少一款 AI 编程工具装在运行守护进程的机器上（不一定是跑服务器的机器——可以是你开发用的笔记本）

1. 拉取项目 + 一键启动后端

git clone https://github.com/nstack-enterprises/concierto-agent-platform
cd concierto-agent-platform
make selfhost

make selfhost 会：

如果没有 .env 文件，从 .env.example 自动生成一份并生成随机 JWT_SECRET
拉取官方 Docker 镜像（PostgreSQL、NSTACK Agents backend、NSTACK Agents frontend）
用 docker-compose.selfhost.yml 启动全部服务
等后端 /health 端点准备就绪

如果是启动完成后的生产探针，想让数据库或 migration 异常也体现为失败，请改用 /readyz。

后端容器启动时会自动跑数据库 migration（docker/entrypoint.sh 在启动 server 前执行 ./migrate up）——你会在 backend 日志里看到 migration 输出。升级版本时同样自动处理。

镜像还没发布？ 如果 make selfhost 报拉不到镜像，可能是你在某个未发布的版本标签上。切到稳定版本或直接从源码构建：make selfhost-build。

启动完成后：

前端：http://localhost:3000
后端：http://localhost:8080

2. 重要：保持生产安全配置

docker-compose.selfhost.yml 默认把 APP_ENV 设成 production，并让 CONCIERTO_DEV_VERIFICATION_CODE 为空，所以公网实例默认没有固定验证码。

只在本地或私有测试自动化里设置 CONCIERTO_DEV_VERIFICATION_CODE。如果在 APP_ENV 非 production 时启用了固定验证码，任何能请求验证码的人都能用这个固定值登录。详见登录与注册配置 → 固定本地测试验证码。

公网部署前一定检查 .env 里 APP_ENV=production，且 CONCIERTO_DEV_VERIFICATION_CODE 为空。

3. 配置邮件服务（可选但推荐）

如果不配邮件，用户无法通过邮件收到验证码；server 会把生成的验证码打印到 stdout。

支持两种发送通道，按部署环境二选一：

Option A — Resend（公网/云端部署）：

在 Resend 注册并拿一个 API key
验证一个你控制的发件域名

在 .env 里设：

RESEND_API_KEY=re_xxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com

Option B — SMTP relay（内网/自部署）：

适合内网无法访问 api.resend.com，或已经有内部邮件中继（Exchange、Postfix、自部署 SendGrid 等）的场景。同时设置时 SMTP_HOST 优先级高于 Resend。

SMTP_HOST=smtp.internal.example.com
SMTP_PORT=587                  # 默认 25；STARTTLS 提交端口用 587
SMTP_USERNAME=concierto          # 留空则使用未认证 relay
SMTP_PASSWORD=...
RESEND_FROM_EMAIL=noreply@yourdomain.com  # 同时作为 SMTP From: 头

之后重启：docker compose -f docker-compose.selfhost.yml restart backend。

更多 auth 配置（OAuth、注册白名单）以及完整的 SMTP 变量说明见登录与注册配置和环境变量。

4. 首次登录 + 创建工作区

打开 http://localhost:3000：

输入你的邮箱
从你配置的邮件后端（Resend 或 SMTP relay）收到的邮件里拿验证码；两者都没配的话，从 server 容器的 stdout 里抄 [DEV] Verification code 这行
不要直接使用 888888；只有在非 production 私有实例上显式设置 CONCIERTO_DEV_VERIFICATION_CODE=888888 后它才会生效
登录后创建第一个工作区

5. 连接命令行工具到你自己的 server

命令行装法和 Cloud 快速上手 → 2. 装命令行工具一样——Homebrew / 脚本 / PowerShell 任选。装好之后，用 self-host 版本的 setup 命令：

concierto setup self-host --server-url http://<你的服务器地址>:8080 --app-url http://<你的服务器地址>:3000

本地就是一台电脑跑整套的话：

concierto setup self-host

默认连 http://localhost:8080（backend）+ http://localhost:3000（frontend）。

setup self-host 会让你在浏览器里完成登录，把 PAT 存到本地，自动启动守护进程。

6. 创建智能体 + 分配第一个任务

流程和 Cloud 一样——见 Cloud 快速上手 → 5-6 步。

常见问题

后端起不来：看容器日志 docker compose -f docker-compose.selfhost.yml logs backend；常见是 .env 里 DATABASE_URL 或 JWT_SECRET 有问题
验证码收不到：没配任何邮件后端（Resend 和 SMTP 都没设） → 从 docker compose logs backend 里找 [DEV] Verification code
WebSocket 连不上：公网部署必须设 FRONTEND_ORIGIN 成你真实的前端域名；见故障排查 → WebSocket 连不上

下一步

环境变量 —— 完整 env 清单
登录与注册配置 —— Resend / OAuth / 注册白名单详细配置
GitHub 集成 —— 连一个 GitHub App，让 PR 自动关联 issue、merge 时自动转 Done
故障排查 —— 遇到问题先来这里
桌面应用 —— 可以通过 ~/.concierto/desktop.json 连接 Desktop；Web 前端 + CLI 仍然是最快的自部署路径

本页目录