social-app/deploy

Production Deploy Package

本目录是单机 docker compose 的生产交付包，架构为：

• 应用层：web + worker-agent + worker-general + scheduler + init-job
• 中间件：redis
• 数据与认证：云 Supabase（通过环境变量访问）
• 反向代理：由服务器侧 nginx 托管（不在本目录编排）

交付物

1. deploy/build-prod-image.sh：构建并导出生产镜像。
2. deploy/docker-compose.prod.yml：生产 Docker Compose 编排。
3. deploy/.env.prod.example：生产环境变量模板。
4. deploy/README.md：部署说明书。

安全基线

• deploy/.env.prod.example 仅作为模板，真实密钥请在服务器上填写到 deploy/.env.prod，不要提交仓库。
• Redis 密码必填；为空时容器会启动失败。
• 后端镜像默认使用非 root 用户运行。
• 容器间通信仅走 Docker 内网（redis 服务名）。

目录结构

deploy/
├── build-prod-image.sh
├── docker-compose.prod.yml
├── .env.prod.example
├── data/
│   └── analytics/
├── static/
│   └── releases/
└── README.md

一次性交付：构建生产镜像

在仓库根目录执行：

bash deploy/build-prod-image.sh

成功后会产出：

• 镜像名：social-app-backend:prod（可用 SOCIAL_BACKEND_IMAGE 覆盖）
• 归档文件：deploy/social-app-backend-prod.tar.gz

如果你要把镜像拷贝到另一台服务器，传输该 .tar.gz 后执行：

gunzip -c social-app-backend-prod.tar.gz | docker load

启动流程（生产）

1) 检查环境变量

先创建生产环境变量文件：

cp deploy/.env.prod.example deploy/.env.prod

确认 deploy/.env.prod 至少包含以下关键变量（云 Supabase 与数据库连接）：

• SOCIAL_SUPABASE__PUBLIC_URL
• SOCIAL_SUPABASE__ANON_KEY
• SOCIAL_SUPABASE__SERVICE_ROLE_KEY
• SOCIAL_SUPABASE__JWT_SECRET
• SOCIAL_DATABASE__HOST
• SOCIAL_DATABASE__PORT
• SOCIAL_DATABASE__NAME
• SOCIAL_DATABASE__USER
• SOCIAL_DATABASE__PASSWORD
• SOCIAL_REDIS__PASSWORD

说明：

• 容器内通信统一使用 Docker 内网：SOCIAL_REDIS__HOST=redis。
• SOCIAL_WEB__HOST 是容器内监听地址，生产建议保持 0.0.0.0。

2) 启动常驻服务

确保 analytics 数据目录已存在（用于持久化 SOCIAL_ANALYTICS__DATA_PATH）：

mkdir -p deploy/data/analytics

如果服务器启用了更严格权限策略（含 rootless Docker 或自定义容器运行用户），请确保该目录对容器运行用户可写：

chmod 775 deploy/data/analytics

docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml up -d redis web worker-agent worker-general scheduler

3) 执行一次性 bootstrap

docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml run --rm init-job

4) 查看状态与日志

docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml ps
docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml logs -f web

停止与重启

停止：

docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml down

重启：

docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml up -d

nginx 对接建议

• 反向代理到 127.0.0.1:${SOCIAL_WEB__PORT}（默认 5775）。
• 仅开放 nginx 对外端口；应用容器仅发布到本机回环地址。
• 如果 nginx 运行在宿主机，web 需要保留 127.0.0.1:host_port:container_port 端口映射。
• 如果 nginx 也运行在 Docker 同网络内，可以移除 web.ports，改为容器内反向代理（例如 proxy_pass http://web:5775）。

App 安装包下载代理（必须配置）

在 nginx 增加静态目录映射：location /releases/ { alias /你的项目绝对路径/deploy/static/releases/; }，这样 https://你的域名/releases/xxx.apk 可直接下载安装包。并在 deploy/.env.prod 设置 SOCIAL_APP_VERSION__DOWNLOAD_BASE_URL=https://你的域名 与 SOCIAL_APP_VERSION__RELEASE_PATH_PREFIX=releases，确保 check-updates 返回的 download_url 指向该路径。

Analytics 数据持久化

• SOCIAL_ANALYTICS__DATA_PATH 默认值是 backend/data/analytics。
• 生产编排已挂载：deploy/data/analytics -> /app/backend/data/analytics。
• web 和 worker-general 共用同一挂载目录，避免写入与读取不一致。
• 若你在 .env.prod 覆盖了 SOCIAL_ANALYTICS__DATA_PATH，请同步调整 docker-compose.prod.yml 的挂载目标路径。
• analytics 挂载为独立目录，不会影响 deploy/static/releases -> /app/deploy/static/releases 的 APK 发布链路。
• 建议将 deploy/data/analytics 纳入日常备份策略，避免宿主机磁盘故障导致数据丢失。

Android APK 打包

打包 Android APK 时需指定后端地址：

bash deploy/build-android-release.sh --backend-host api.linksy.chat --channel release

后端地址：https://api.linksy.chat

已知约束

• init-job 为一次性任务，不长期驻留。