# OMNIAXS Docker 部署指南（2026）

## 1. 部署目标
本指南用于 **prod 基线部署**：
1. API Gateway 与多页面前端同域发布。
2. PostgreSQL 持久化启用（业务数据重启不丢失）。
3. 管理能力支持 JWKS（推荐）与 local_jwt（仅联调）。
4. SMTP 通知链路可由超管页面触发联调。

## 2. 前置要求
1. Docker `24+`。
2. Docker Compose `v2+`。
3. 可用端口：`8000`、`5432`。

## 3. 启动（推荐）
在仓库根目录执行：

```bash
docker compose up --build -d
```

检查：

```bash
docker compose ps
docker compose logs -f api-gateway
docker compose logs -f postgres
```

## 4. 当前 Compose 组件
`docker-compose.yml` 已包含：
1. `postgres`（持久化卷：`omniaxs-pgdata`）。
2. `api-gateway`（包含前端静态站点挂载）。

## 5. 核心环境变量
### 5.1 持久化与运行模式
1. `PM_RUNTIME_ENV=prod`
2. `PM_DATABASE_URL=postgresql://...`
3. `PM_PERSISTENCE_REQUIRED=true`

### 5.2 Partner 鉴权
1. `PM_PARTNER_CREDENTIALS_JSON`（推荐，支持多 key 轮换）
2. 未配置时回退 `PM_DEFAULT_API_KEY/PM_DEFAULT_API_SECRET`（仅联调）

### 5.3 Admin 鉴权（推荐 JWKS）
1. `PM_ADMIN_AUTH_MODE=jwks`
2. `PM_ADMIN_JWKS_URL=<your-jwks-url>`
3. `PM_ADMIN_ISSUER=<issuer>`
4. `PM_ADMIN_AUDIENCE=<audience>`
5. `PM_ADMIN_REQUIRED_SCOPE=admin:super`

联调模式（不建议生产）：
1. `PM_ADMIN_AUTH_MODE=local_jwt`
2. `PM_ADMIN_LOCAL_JWT_SECRET=<strong-secret>`

### 5.4 SMTP 通知
1. `PM_SMTP_HOST`
2. `PM_SMTP_PORT`
3. `PM_SMTP_USERNAME`
4. `PM_SMTP_PASSWORD`
5. `PM_SMTP_SENDER`
6. `PM_SMTP_USE_TLS=true`
7. `PM_SMTP_DEFAULT_RECIPIENTS=ops@...,secops@...`

## 6. 部署后验证
### 6.1 基础可用性

```bash
curl -sS http://127.0.0.1:8000/healthz
```

预期：

```json
{"status":"ok"}
```

### 6.2 页面入口
1. `http://127.0.0.1:8000/`
2. `http://127.0.0.1:8000/user-login.html`
3. `http://127.0.0.1:8000/user-portal.html`
4. 管理控制台入口仅内部发放，不在公开页面展示

### 6.3 状态接口（签名）
1. `GET /v1/status` 返回 `mode=production`（prod）。
2. 组件列表包含 `state-store`。

### 6.4 超管接口
1. `GET /internal/v1/admin/observability/summary`
2. `GET /internal/v1/admin/notifications/config`

## 7. 数据可靠性说明
1. 关键业务状态采用“内存热数据 + PostgreSQL 同步快照”写入模式。
2. 每次关键写操作（订单、审批、绑定、告警、凭证、waitlist）后立即持久化。
3. 服务启动时优先从 PostgreSQL 恢复状态。
4. PostgreSQL 数据卷默认保留在 `omniaxs-pgdata`。

## 8. Cloudflare / HTTPS
你已指定由 Cloudflare 统一处理 HTTPS 与域名 `omniaxs.com`，本仓库不做 Cloudflare 侧配置。

## 9. 停止与清理
停止：

```bash
docker compose down
```

包含卷清理（谨慎执行）：

```bash
docker compose down -v --rmi local
```

## 10. 常见问题
### 10.1 `PM_DATABASE_URL` 未配置
prod 模式会直接拒绝启动（防止误用内存态）。

### 10.2 Admin 403
1. 检查 `Authorization: Bearer ...`。
2. 检查 `X-PM-ROLE`。
3. 若启用 JWKS，检查 `issuer/audience/scope`。

### 10.3 SMTP 返回 skipped
说明 SMTP 参数尚未配置完整，属于预期行为。