部署 Node / Docker

标准部署由一个 Node 应用、PostgreSQL 和 S3 兼容对象服务组成。应用同时提供 HTTP API、Dashboard 和设备 WebSocket；Redis 只在跨副本设备路由时需要。

首次体验先完成启动第一个网关。本页说明如何把它变成长期运行的实例。

理解需要保存的三类数据

客户端 → TLS 反向代理 → Node 应用
                         ├─ PostgreSQL：节点、身份、配置、Store / Mailbox 元数据
                         ├─ S3：Context 与 Store 对象字节
                         └─ bootstrap：实例身份、连接、加密与签名根

三部分共同构成可恢复的实例。数据库是唯一生产权威状态；当前服务端不提供 SQLite、本地文件对象存储或旧配置导入。设备自身暴露本地目录仍受支持。

使用发布版 Compose

从网关仓库运行：

docker compose -f deploy/compose/docker-compose.yml up -d
docker compose -f deploy/compose/docker-compose.yml ps -a
docker compose -f deploy/compose/docker-compose.yml exec app \
  node /app/dist/admin.js pair

清单包括初始化任务、PG、SeaweedFS、桶初始化与 app，凭证自动生成并以最小范围挂载。随后在 /ui/ 使用配对 token 完成安装。固定并记录你使用的清单、镜像版本或 digest。

根 docker-compose.yml 用于源码构建；deploy/compose/docker-compose.yml 使用发布镜像。启动、配对、重启与停止要始终使用同一清单。

设置公开入口

为网关配置 HTTPS 反向代理，保留 Host、Authorization 和 WebSocket upgrade。Dashboard 最好与 API 同源，只对 /ui/* 做前端路由回退。

在安装界面或受管理配置中设置 canonicalOrigin 为公开 HTTPS 地址。它影响 OAuth 回调和代理后的对象 URL 协议。不要依赖客户端可伪造的 X-Forwarded-Proto 修改安全边界。

产品设置保存在 PG；标准可执行入口只接受监听端口和 bootstrap 位置等最小启动信息。旧 TB_DATABASE_URL、TB_OBJECT_STORE_*、TB_CANONICAL_ORIGIN 等环境变量不再是部署配置入口。

读懂健康状态

探针	说明
/livez	进程存活，不以 PG 抖动触发重启
/healthz	版本、实例与安装状态；安装态也能成功
/readyz	业务已初始化且 PG、active S3、已配置 Redis 可用；恢复、维护和 draining 时为 503

curl --fail https://tb.example.com/readyz
tb login --base-url https://tb.example.com --profile production
tb use production
tb help system/status
tb call system/status/get

收到 SIGTERM 后，readiness 先失败，再按已应用的 shutdownDrainSec 等待并排空请求、设备和后台工作。把这个值与编排器的摘流量周期对齐；仅保存尚未 apply 的值不会改变关停行为。

通过本机执行器管理 Compose 应用

在部署主机安装并登录 CLI，然后启动受限执行器：

tb deployment get
tb deployment agent --compose ./deploy/compose/docker-compose.yml

管理员可通过 Dashboard 部署页或 tb deployment update 保存期望设置。执行器只管理选定 Compose 文件的 app，支持 schema 允许的镜像、端口、绑定地址和目录。应用容器不持有 Docker socket。

保存设置不等于完成部署：查看 tb deployment status 的 agent 与任务结果。执行器会核对真实容器和实例身份，失败尝试恢复旧配置。它不会代替 Railway 或 Kubernetes 的平台部署工具。

Railway 与容器 PaaS

Railway 使用 Dockerfile.railway，并把持久卷运行时挂到 /data。PG/S3 连接通过受保护的安装流程提供，不恢复旧 env-only 配置。

平台卷若属于 root，启动阶段需要设置 /data 与 /data/bootstrap 的 owner 和权限，然后降权运行应用；只修改 bootstrap 子目录仍可能无法创建旁侧锁文件。私网 S3 的 exact origin 必须由本机受保护的安装 defaults 授权，公开表单不能任意放行内网。

经容器 loopback 安装时，在实际 setup 请求里显式填写公开 canonicalOrigin；安装返回的 loopback baseUrl 不应用作远程客户端地址。

上线与后续管理

• 新增或切换对象服务：存储后端。
• 改域名、限额和调度：受管理配置。
• 备份、数据库迁移和密钥轮换：维护与恢复。
• 多副本：Kubernetes 与多副本。
• 开放访问前：上线检查清单。