qzl
163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
# 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` 服务名）。
|
|
|
|
## 目录结构
|
|
|
|
```text
|
|
deploy/
|
|
├── build-prod-image.sh
|
|
├── docker-compose.prod.yml
|
|
├── .env.prod.example
|
|
├── data/
|
|
│ └── analytics/
|
|
├── static/
|
|
│ └── releases/
|
|
└── README.md
|
|
```
|
|
|
|
## 一次性交付：构建生产镜像
|
|
|
|
在仓库根目录执行：
|
|
|
|
```bash
|
|
bash deploy/build-prod-image.sh
|
|
```
|
|
|
|
成功后会产出：
|
|
|
|
- 镜像名：`social-app-backend:prod`（可用 `SOCIAL_BACKEND_IMAGE` 覆盖）
|
|
- 归档文件：`deploy/social-app-backend-prod.tar.gz`
|
|
|
|
如果你要把镜像拷贝到另一台服务器，传输该 `.tar.gz` 后执行：
|
|
|
|
```bash
|
|
gunzip -c social-app-backend-prod.tar.gz | docker load
|
|
```
|
|
|
|
## 启动流程（生产）
|
|
|
|
### 1) 检查环境变量
|
|
|
|
先创建生产环境变量文件：
|
|
|
|
```bash
|
|
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`）：
|
|
|
|
```bash
|
|
mkdir -p deploy/data/analytics
|
|
```
|
|
|
|
如果服务器启用了更严格权限策略（含 rootless Docker 或自定义容器运行用户），请确保该目录对容器运行用户可写：
|
|
|
|
```bash
|
|
chmod 775 deploy/data/analytics
|
|
```
|
|
|
|
```bash
|
|
docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml up -d redis web worker-agent worker-general scheduler
|
|
```
|
|
|
|
### 3) 执行一次性 bootstrap
|
|
|
|
```bash
|
|
docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml run --rm init-job
|
|
```
|
|
|
|
### 4) 查看状态与日志
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
## 停止与重启
|
|
|
|
停止：
|
|
|
|
```bash
|
|
docker compose --env-file deploy/.env.prod -f deploy/docker-compose.prod.yml down
|
|
```
|
|
|
|
重启：
|
|
|
|
```bash
|
|
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
|
|
bash deploy/build-android-release.sh --backend-host http://115.190.63.157 --channel release
|
|
```
|
|
|
|
后端地址：`http://115.190.63.157`
|
|
|
|
## 已知约束
|
|
|
|
- `init-job` 为一次性任务，不长期驻留。
|