XuqmGroup-PrivateDeploy/docs/configuration.md

# 配置说明

## `.env`

部署入口配置，控制镜像版本、服务 profile、域名和 MySQL/Redis 模式。

关键字段：

- `REGISTRY`：私有 Docker 镜像仓库。
- `IMAGE_TAG`：本次部署镜像版本。
- `COMPOSE_PROFILES`：启用的服务集合，例如 `base,im,push,update,license`。
- `MYSQL_MODE`：`external` 或 `managed`。
- `REDIS_MODE`：`external` 或 `managed`。
- `ENABLE_IM`、`ENABLE_PUSH`、`ENABLE_UPDATE`、`ENABLE_LICENSE`：运行时功能开关。

## `config/secrets.env`

敏感配置文件，不提交 Git。

关键字段：

- `MYSQL_PASSWORD`
- `MYSQL_ROOT_PASSWORD`
- `REDIS_PASSWORD`
- `SMTP_PASSWORD`

托管模式下，如果密码为空或为 `change-me`，脚本会自动生成并写回该文件。

## `config/xuqm.env`

业务服务共享配置，包含私有化运行模式、单租户初始化、域名和基础中间件连接信息。

私有化必须保持：

```env
DEPLOYMENT_MODE=PRIVATE
TENANT_REGISTER_ENABLED=false
TENANT_BOOTSTRAP_ENABLED=true
```

## Spring Boot 数据库 URL 覆盖（重要）

`tenant-service` 和 `file-service` 的 `application.yml` 中数据库 URL 编译期写死了生产地址。
私有化部署**必须**通过 `docker-compose.yml` 的 `environment:` 节覆盖 Spring Boot 配置：

```yaml
environment:
  SPRING_DATASOURCE_URL: "jdbc:mysql://${MYSQL_HOST}:${MYSQL_PORT:-3306}/${MYSQL_DATABASE:-xuqm_private}?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=GMT%2B8&allowPublicKeyRetrieval=true"
  SPRING_DATASOURCE_USERNAME: "${MYSQL_USERNAME:-xuqm}"
  SPRING_DATASOURCE_PASSWORD: "${MYSQL_PASSWORD}"
  SPRING_DATA_REDIS_HOST: "${REDIS_HOST}"
  SPRING_DATA_REDIS_PORT: "${REDIS_PORT:-6379}"
  SPRING_DATA_REDIS_PASSWORD: "${REDIS_PASSWORD}"
  SPRING_DATA_REDIS_DATABASE: "${REDIS_DATABASE:-0}"
```

这些 `${VAR}` 在启动时由 Docker Compose 从 `.env` 文件展开，优先级高于 `env_file:` 中的同名变量。
当前 `docker-compose.yml` 已包含上述覆盖，不需要手动修改。

## Nginx 服务端口

| 服务 | 容器内端口 | nginx 路由 |
|------|-----------|-----------|
| tenant-service | **9001** | `/api/`（兜底），`/actuator/` |
| file-service | **8086** | `/file/` |
| im-service | **8082** | `/api/im/`，`/ws/im/`（WebSocket） |
| push-service | **8083** | 厂商回调（不直接暴露给前端） |
| update-service | **8084** | `/api/v1/updates/`，`/api/v1/rn/` |
| license-service | **8085** | 内部调用 |
| ops-web | 80 | `/ops` |
| tenant-web | 80 | `/`（根路径） |

## 可选服务内部通信

im-service 和 update-service 在调用 tenant-service 内部 API 时，需要显式覆盖默认地址：

```yaml
# im-service
environment:
  TENANT_SERVICE_URL: "http://tenant-service:9001"
  PUSH_SERVICE_URL: "http://push-service:8083"

# update-service
environment:
  SDK_TENANT_SERVICE_URL: "http://tenant-service:9001"
```

push-service 默认已使用 `http://tenant-service:9001`，无需额外配置。

`docker-compose.yml` 已包含上述覆盖，不需要手动修改。

## docs-site 镜像

`docs-site` 镜像在部分 ACR namespace 下不存在。`docker-compose.yml` 已将 nginx 对 `docs-site` 的依赖标记为 `required: false`，镜像缺失时 nginx 仍可正常启动，`healthcheck.sh` 将 docs-site 容器计为可选（WARN 而非 FAIL）。

## `config/sdk/xuqm-private-sdk.json`

私有化 SDK 初始化配置，由 `scripts/render-config.sh` 生成。

文档站和客户应用示例必须使用该文件，不再指向 `dev.xuqinmin.com` 公有化逻辑。

## `config/vendors`

厂商能力配置：

- `push.env`：华为、小米、OPPO、vivo、荣耀 Push 凭据。
- `store-submit.env`：华为、小米、OPPO、vivo、荣耀应用市场自动发布凭据。

## `config/mail/smtp.env`

邮件服务配置。生产环境必须使用客户提供的 SMTP 服务。