企业官网建设流程全解析

thepopebot 是一款可以 7×24 小时自主运行的 AI Agent（智能体），既能陪你在网页、Telegram 里聊天，还能自动写代码、开 PR、合并后私聊通知你。本地跑起来容易，但要让它真正稳定在线，推荐部署到一台 VPS 上，用 Docker Compose 编排服务、Traefik 做反向代理、Let's Encrypt 免费签发 HTTPS 证书。本文带你走通这套the Pope Bot 生产环境部署的完整流程。

一、部署前准备：服务器与域名清单

任何云厂商的 VPS 都可以（Hetzner、DigitalOcean、AWS 等），提前按下面清单备好：

💡 注意：即使最终走 HTTPS，80 端口也必须开放——Let's Encrypt 通过 80 端口的 HTTP 挑战验证域名归属。

详细要求可参考项目自带的部署文档：docs/DEPLOYMENT.md。

二、先搞懂架构：Docker Compose 里的 4 个容器

thepopebot 的编排文件 templates/docker-compose.yml 定义了 4 个服务，各司其职：

浏览器 / Telegram │ ▼ ┌─────────┐ 反代+TLS ┌────────────────┐ │ traefik │ ──────────► │ event-handler │── Docker socket ──► 编码Agent容器 └─────────┘ └────────────────┘ （后台任务/代码工作区）

两个关键设计：

• 预构建镜像：.next/和node_modules直接烘焙进镜像（见 docker/event-handler/Dockerfile），部署时容器内不会再跑npm install或next build，启动很快。
• 只挂载你的目录：项目目录仅把agent-job/、skills/、data/、.env、logs/等用户可编辑部分挂载进容器，镜像内部的构建产物永不被覆盖。

三、一键脚手架：两行命令生成项目

SSH 登录服务器后执行：

mkdir my-agent && cd my-agent npx thepopebot@latest init npm run setup

• init会生成完整项目骨架（含工作流、Compose 文件、模板提示词），也可以用git clone https://gitcode.com/gh_mirrors/th/thepopebot浏览源码对照理解。
• setup是交互式向导：检查前置依赖、创建仓库、生成 PAT、配置 URL 并启动 Docker。

向导问到APP_URL时，务必填带https://的生产地址（如https://mybot.example.com）。

最后让 CI 工作流跑在你自己的 Runner 上，而不是 GitHub 托管机器：

gh variable set RUNS_ON --body "self-hosted" --repo OWNER/REPO

四、启用 HTTPS：两种方案任选其一

方案 A：内置 Let's Encrypt（HTTP 挑战）

默认的 templates/docker-compose.yml 已经内置 Let's Encrypt 配置，只是被注释掉了，按 docs/DEPLOYMENT.md 做三处修改即可：

1. .env添加邮箱：LETSENCRYPT_EMAIL=you@example.com
2. 取消注释 Traefik 的 TLS 参数（共 5 行），开启 HTTP→HTTPS 自动跳转和 ACME 证书解析器
3. event-handler 路由从 HTTP 切到 HTTPS：注释掉entrypoints=web，放开entrypoints=websecure和tls.certresolver=letsencrypt两行

改动示意：

# 注释掉 HTTP 入口 # - traefik.http.routers.event-handler.entrypoints=web # 放开 HTTPS 两行 - traefik.http.routers.event-handler.entrypoints=websecure - traefik.http.routers.event-handler.tls.certresolver=letsencrypt

方案 B：通配符证书（DNS 挑战，一条命令搞定）

如果域名要挂多个子域名，推荐用内置的 SSL 向导：

npx thepopebot setup-ssl

该向导（源码见 setup/setup-ssl.mjs）会交互式地让你输入域名、Let's Encrypt 通知邮箱，并从 Cloudflare、AWS Route 53、DigitalOcean、Namecheap、GoDaddy、Porkbun 中选择你的 DNS 服务商填入 API 凭据。它会自动完成：

• 通过 DNS 服务商 API 创建*.yourdomain通配符记录
• 写入SSL_DOMAIN、SSL_EMAIL、SSL_DNS_PROVIDER到.env，凭据单独存进.env.traefik
• 把 Compose 文件切换为 templates/docker-compose.custom.yml——这个文件启用了 DNS 挑战，可签发通配符证书，且不受升级覆盖

五、启动并验证：三条命令确认上线

docker compose up -d docker compose ps # 确认全部 running / healthy curl -I https://mybot.example.com/api/ping

event-handler 自带健康检查（每 10 秒探测/api/ping，见 templates/docker-compose.yml），/api/ping返回正常即代表 HTTPS 链路已打通。此时浏览器访问你的域名，应看到登录页——首次访问证书自动签发，稍等片刻即可看到安全锁 🔒。

六、部署后必做的三项配置

登录管理后台，按顺序配置这三项后才能开聊、跑任务（顺序很重要）：

1. LLM 供应商密钥—/admin/event-handler/llms，添加 Anthropic / OpenAI / Google 等 API Key
2. Helper LLM—/admin/event-handler/helper-llm，为自动生成会话标题、PR 摘要等一次性调用选模型
3. 编码 Agent—/admin/event-handler/coding-agents，选择驱动聊天、代码工作区和后台任务的 Agent（Claude Code、Pi、Codex、Gemini、OpenCode、Kimi 共 6 种）

可选：在/admin/event-handler/telegram接入 Telegram，实现手机上随时指挥你的机器人。

七、升级与安全建议

升级只需一条命令：

npx thepopebot upgrade # 最新稳定版 npx thepopebot upgrade 1.2.72 # 指定版本

它会安装新包、同步受管文件、重建并重启容器；你的SYSTEM.md、.env、secrets等自定义文件永不被覆盖。升级故障恢复方法见 docs/UPGRADE.md。

安全红线（摘自 docs/SECURRENCY.md，生产环境请务必重视）：

• 务必设置TELEGRAM_WEBHOOK_SECRET与GH_WEBHOOK_SECRET——未配置时 webhook 端点会直接拒绝一切请求（fail-closed）
• 通过 Web UI 生成 API Key 后再对外暴露服务
• 保持自动合并的ALLOWED_PATHS收紧（默认仅/logs），Agent 生成的 PR 先人工审查再合并
• 用你自己的 Telegram 账号绑定验证（/profile/telegram生成校验码），未验证的会话会被静默丢弃

写在最后

至此，一台 VPS 上就拥有了一个带 HTTPS 的 thepopebot 生产实例：Traefik 负责证书与路由，event-handler 负责"大脑"，Docker 负责在隔离容器里跑编码 Agent，runner 负责无人值守升级。整套流程只有脚手架、配 SSL、docker compose up -d三步核心操作，之后把调教 Agent 的时间交给聊天和任务本身就好 🚀

参考资料

• 部署全流程：docs/DEPLOYMENT.md
• Compose 编排模板：templates/docker-compose.yml、templates/docker-compose.custom.yml
• SSL 向导源码：setup/setup-ssl.mjs
• 安全机制说明：docs/SECURITY.md
• 架构总览：docs/ARCHITECTURE.md
• CLI 命令参考：docs/CLI.md