文档

自托管部署

仓库里还没有 docker-compose.yml，所以这一页只提供手动部署步骤——不展示不存在的一键命令。

生产环境三条红线：JOINT_DEV_MODE=1 只能用于本地调试；不要裸跑 HTTP，必须配置 HTTPS/WSS；实时会话注册表在内存中，暂时无法横向扩容，重启会断开会话。

手动部署

git clone <repo> && cd joint/server
npm install
cp .env.example .env   # 按下表填写
npm run migrate
npm run start

建议用 systemd 或 pm2 守护进程，确保崩溃后自动拉起。

环境变量

PORT=8080                 # 监听端口
JOINT_DEV_MODE=0          # 生产必须为 0
DATABASE_URL=file:./joint.db   # SQLite 或 postgres://...
JWT_SECRET=<随机 32 字节>       # 令牌签名密钥
PAIRING_HMAC_SECRET=<随机值>   # 配对码摘要密钥
SMTP_HOST=…  SMTP_PORT=…  SMTP_USER=…  SMTP_PASS=…
MAIL_FROM=joint@yourdomain.com
PUSH_PROVIDER_KEY=<推送服务密钥>

邮件服务

—登录验证码依赖 SMTP，未配置时用户无法登录
—建议使用带独立发信域名的服务，降低验证码进垃圾箱的概率
—开发模式下验证码会打印在后端日志中，生产环境务必关闭

HTTPS / WSS 反向代理

server {
  listen 443 ssl;
  server_name joint.example.com;

  location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
  }
}

缺少 Upgrade / Connection 头会导致实时会话连不上，只有通知能用。

数据库：SQLite 还是 PostgreSQL

—SQLite：单人或小团队自用，零运维，备份就是复制一个文件
—PostgreSQL：多人共用、需要定期备份与监控时更合适
—两者数据模型一致，可通过导出/导入迁移

备份、升级与迁移

# SQLite 备份
sqlite3 joint.db ".backup joint-$(date +%F).db"

# 升级
git pull && npm install && npm run migrate && systemctl restart joint

升级前先备份数据库；迁移脚本是向前兼容的，回滚需要用备份恢复。

健康检查与日志

—健康检查：GET /health 返回 200 即视为存活
—日志默认输出到 stdout，由 systemd/pm2 或 Docker 收集
—关注日志中的配对失败、限流触发与 WebSocket 断开记录

推送通知

—需要配置推送服务密钥，否则只有 App 前台时能看到消息
—iOS 与 Android 分别需要各自的推送凭证
—推送内容只包含事件类型与会话标识，不携带终端正文