docs: 补充 Ubuntu+MySQL 并存与 PostgreSQL 部署指南

DEPLOY-MINI-PROGRAM-H5 增加 PG 安装三种方式、Go API systemd、Checklist 与双库架构说明。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/DEPLOY-MINI-PROGRAM-H5.md

@@ -50,67 +50,223 @@ export const YXG_H5_HOME_URL = `${YXG_H5_BASE}?mp=1`
 | downloadFile 合法域名 | `https://miniapp.yuxingu.com.cn`（维持现状） |
 | socket 合法域名 | 无需配置 |
 
-### 2.3 服务器
+### 2.3 服务器（Ubuntu 典型）
 
-- 一台可跑 Nginx + Go 二进制（或容器）的 VPS
+| 软件 | 用途 | 端口 |
-- PostgreSQL（Go API 用；可与现有库同机或托管）
+|------|------|------|
-- Java 微服务 + `miniapp.yuxingu.com.cn` 保持现有部署，本说明不覆盖
+| **MySQL** | Java 旧后台（`miniapp.yuxingu.com.cn`） | 3306 |
+| **PostgreSQL** | Go API 愈心魔方（**必须另装，不能复用 MySQL**） | 5432 |
+| **Nginx** | HTTPS、`h5.yuxingu.com.cn` 静态 + 反代 | 443 |
+| **Go 二进制** | `yuxingu-api`，建议仅监听 `127.0.0.1:8080` | 8080 |
+
+Java 微服务 + `miniapp.yuxingu.com.cn` 保持现有部署，本说明不覆盖 Java/MySQL 的运维。
+
+### 2.4 双数据库说明（Ubuntu 上已是 MySQL）
+
+**愈心谷 Go API 只支持 PostgreSQL**（pgx + `apps/api/migrations/` 内 PG 语法）。  
+**不能**把 `config.local.yaml` 指到 MySQL，也**不要**把 Java 的 MySQL 表直接给 Go 用。
+
+| 业务 | 后端 | 数据库 |
+|------|------|--------|
+| 小程序：咨询 / 测评 / 订单 / 登录 | Java（rp-server-psychic） | **MySQL**（已有） |
+| 愈心魔方 H5：档案 / 问答 / 报告等 | Go（digital-psychology） | **PostgreSQL**（新增） |
+
+推荐：**同一台 Ubuntu 上 MySQL 与 PostgreSQL 并存**（端口不同，互不影响）。
+
+```
+Ubuntu VPS
+├── MySQL      :3306  → miniapp.yuxingu.com.cn（不动）
+├── PostgreSQL :5432  → 愈心魔方 Go API（新增）
+├── yuxingu-api :8080 → 127.0.0.1（Nginx 反代）
+└── Nginx :443
+    ├── h5.yuxingu.com.cn/psy/      → user-h5 静态
+    └── h5.yuxingu.com.cn/psy/api/  → Go API
+```
 
 ---
 
-## 3. Go API 部署
+## 3. PostgreSQL 部署（Ubuntu）
+
+Go API 启动前必须先有可用的 PostgreSQL 实例。
+
+### 3.1 方式 A：系统包安装（推荐，与 MySQL 并存）
+
+```bash
+# Ubuntu 22.04 / 24.04
+sudo apt update
+sudo apt install -y postgresql postgresql-contrib
+sudo systemctl enable postgresql
+sudo systemctl start postgresql
+
+# 确认端口（默认 5432，与 MySQL 3306 不冲突）
+ss -tlnp | grep 5432
+```
+
+创建专用库与用户（**请替换强密码**）：
+
+```bash
+sudo -u postgres psql <<'SQL'
+CREATE USER yuxingu WITH PASSWORD '替换为强密码';
+CREATE DATABASE yuxingu OWNER yuxingu;
+GRANT ALL PRIVILEGES ON DATABASE yuxingu TO yuxingu;
+SQL
+```
+
+仅本机访问（默认已是）时可加固：
+
+```bash
+# 可选：确认 listen 仅 localhost（/etc/postgresql/*/main/postgresql.conf）
+# listen_addresses = 'localhost'
+sudo systemctl reload postgresql
+```
+
+连通性自测：
+
+```bash
+psql "postgresql://yuxingu:替换为强密码@127.0.0.1:5432/yuxingu?sslmode=disable" -c 'SELECT 1'
+```
+
+### 3.2 方式 B：Docker 只跑 Postgres（系统 MySQL 不动）
+
+已安装 Docker 时，可不必 `apt install postgresql`：
+
+```bash
+docker run -d --name yuxingu-pg \
+  --restart unless-stopped \
+  -e POSTGRES_USER=yuxingu \
+  -e POSTGRES_PASSWORD='替换为强密码' \
+  -e POSTGRES_DB=yuxingu \
+  -p 127.0.0.1:5432:5432 \
+  -v yuxingu-pg-data:/var/lib/postgresql/data \
+  postgres:16-alpine
+```
+
+`config.local.yaml` 中 `database.host` 仍为 `127.0.0.1`，`port: 5432`。
+
+### 3.3 方式 C：云托管 PostgreSQL
+
+使用 RDS / 云数据库 PostgreSQL 时，将 `config.local.yaml` 的 `database.host` 改为云内网地址，并按云厂商要求设置 `sslmode`（常为 `require`）。  
+安全组需允许 **应用服务器** 访问 5432，**不要**对公网开放 PostgreSQL。
+
+### 3.4 迁移说明
+
+- 表结构由 Go API **启动时自动迁移**（`apps/api/migrations/`），无需手工导入 SQL。
+- 首次 `./yuxingu-api` 或 `systemctl start yuxingu-api` 成功后，库内应有 `migrations` 相关表及业务表。
+- **禁止**把 Java MySQL 的 `psychic_*` 表导入 PostgreSQL 替代迁移。
+
+---
+
+## 4. Go API 部署
 
 仓库：`digital-psychology`
 
-### 3.1 构建
+### 4.1 服务器目录建议
 
 ```bash
-cd /path/to/digital-psychology/apps/api
+sudo mkdir -p /opt/yuxingu
+sudo chown "$USER:$USER" /opt/yuxingu
+
+# 拉代码（示例）
+cd /opt/yuxingu
+git clone https://git.jackyu66.com/jack/digital-psychology.git
+cd digital-psychology/apps/api
+```
+
+也可在本机构建 `yuxingu-api` 二进制 + scp 到服务器，仅同步 `apps/api/` 与 `config.local.yaml`。
+
+### 4.2 构建
+
+```bash
+cd /opt/yuxingu/digital-psychology/apps/api
 go test ./...
 go build -o yuxingu-api ./cmd/server
 ```
 
-### 3.2 配置
+服务器若无 Go  toolchain，在开发机交叉编译后上传：
 
 ```bash
+# 开发机（Linux amd64 示例）
+GOOS=linux GOARCH=amd64 go build -o yuxingu-api ./cmd/server
+scp yuxingu-api user@server:/opt/yuxingu/digital-psychology/apps/api/
+```
+
+### 4.3 配置（生产）
+
+```bash
+cd /opt/yuxingu/digital-psychology/apps/api
 cp config.example.yaml config.local.yaml
-# 编辑 config.local.yaml：database、deepseek.api_key（Ask 需要）等
+chmod 600 config.local.yaml
 ```
 
-生产环境建议用环境变量覆盖敏感项，勿把密钥提交 Git。
+`config.local.yaml` 示例（**PostgreSQL，非 MySQL**）：
 
-### 3.3 数据库迁移
+```yaml
+app:
+  env: prod
+  http_addr: "127.0.0.1:8080"   # 仅本机，由 Nginx 反代对外
 
-API 启动时会自动应用 `apps/api/migrations/`。首次部署前确保 PostgreSQL 已创建库和用户。
+database:
+  host: 127.0.0.1
+  port: 5432
+  user: yuxingu
+  password: "替换为强密码"
+  name: yuxingu
+  sslmode: disable
+
+deepseek:
+  api_key: ""          # Ask 真实回复需要；展示可先留空
+  base_url: "https://api.deepseek.com"
+  model: "deepseek-chat"
+  timeout_sec: 60
+
+admin:
+  bootstrap_username: admin
+  bootstrap_password: "替换为强密码"
+```
+
+生产环境建议用环境变量 / 密钥管理覆盖敏感项，勿把 `config.local.yaml` 提交 Git。
+
+### 4.4 首次启动与迁移
 
 ```bash
-# 本地仅 DB 示例
+cd /opt/yuxingu/digital-psychology/apps/api
-cd /path/to/digital-psychology
+./yuxingu-api
-docker compose -f docker-compose.dev.yml up -d
+# 看到监听 127.0.0.1:8080、迁移无报错即可 Ctrl+C，改 systemd 常驻
 ```
 
-### 3.4 运行（示例 systemd）
+### 4.5 systemd 常驻
 
 ```ini
 # /etc/systemd/system/yuxingu-api.service
 [Unit]
-Description=Yuxingu Go API
+Description=Yuxingu Go API (愈心魔方)
-After=network.target
+After=network.target postgresql.service
+Wants=postgresql.service
 
 [Service]
 Type=simple
-WorkingDirectory=/opt/yuxingu/apps/api
+User=www-data
-ExecStart=/opt/yuxingu/apps/api/yuxingu-api
+Group=www-data
+WorkingDirectory=/opt/yuxingu/digital-psychology/apps/api
+ExecStart=/opt/yuxingu/digital-psychology/apps/api/yuxingu-api
 Environment=APP_ENV=prod
 Restart=on-failure
+RestartSec=5
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-API 默认监听 `:8080`（见 `config.local.yaml` 的 `http_addr`）。
+若 PostgreSQL 用 Docker 容器名 `yuxingu-pg`，将 `After=` 改为 `docker.service` 或去掉 PostgreSQL 依赖。
 
-### 3.5 健康检查
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable yuxingu-api
+sudo systemctl start yuxingu-api
+sudo systemctl status yuxingu-api
+```
+
+### 4.6 健康检查
 
 ```bash
 curl -sS http://127.0.0.1:8080/api/v1/healthz
@@ -119,9 +275,9 @@ curl -sS http://127.0.0.1:8080/api/v1/healthz
 
 ---
 
-## 4. H5 构建与 Nginx 部署
+## 5. H5 构建与 Nginx 部署
 
-### 4.1 构建静态资源
+### 5.1 构建静态资源
 
 ```bash
 cd /path/to/digital-psychology
@@ -132,7 +288,7 @@ npm run build:h5
 
 构建产物 `base` 为 `/psy/`，与线上路径一致，**无需改 `baseURL`**（客户端请求 `/psy/api/v1/...`）。
 
-### 4.2 上传到服务器
+### 5.2 上传到服务器
 
 ```bash
 rsync -avz --delete apps/user-h5/dist/ user@your-server:/var/www/yuxingu-h5/psy/
@@ -147,7 +303,7 @@ rsync -avz --delete apps/user-h5/dist/ user@your-server:/var/www/yuxingu-h5/psy/
 └── ...
 ```
 
-### 4.3 Nginx 配置（推荐：H5 + API 同域）
+### 5.3 Nginx 配置（推荐：H5 + API 同域）
 
 ```nginx
 server {
@@ -194,7 +350,7 @@ reload：
 sudo nginx -t && sudo systemctl reload nginx
 ```
 
-### 4.4 H5 embed 模式说明
+### 5.4 H5 embed 模式说明
 
 小程序 WebView 打开 `https://h5.yuxingu.com.cn/psy/?mp=1` 时：
 
@@ -204,13 +360,43 @@ sudo nginx -t && sudo systemctl reload nginx
 
 浏览器直访 `https://h5.yuxingu.com.cn/psy/`（无 `mp=1`）仍为完整 H5 体验（含 TabBar）。
 
+### 5.5 ICP 备案页脚
+
+`user-h5` / `admin-h5` 构建产物已含底部链接：**蜀ICP备2025140386号-2** → `https://beian.miit.gov.cn/`。  
+部署 H5 后访问 `https://h5.yuxingu.com.cn/psy/` 应能在页面底部看到备案号。
+
 ---
 
-## 5. 微信小程序部署
+## 6. 运营后台 admin-h5（可选）
+
+若需部署内部 Ops 后台（与愈心魔方同 Go API）：
+
+```bash
+cd /path/to/digital-psychology
+npm ci
+npm run build:admin
+# 产物：apps/admin-h5/dist/
+```
+
+Nginx 可增加 location（与 H5 同机示例）：
+
+```nginx
+location /psy/admin/ {
+    alias /var/www/yuxingu-admin/dist/;
+    try_files $uri $uri/ /psy/admin/index.html;
+}
+```
+
+admin 前端请求走 `/psy/api/` 或 `/api/` 反代（与 `apps/admin-h5` 构建 `base` 一致）。  
+登录使用 `config.local.yaml` 中 `admin.bootstrap_*` 初始账号。
+
+---
+
+## 7. 微信小程序部署
 
 仓库：`yuxingu-Miniprogram-dev`
 
-### 5.1 开发工具构建
+### 7.1 开发工具构建
 
 1. 用 **HBuilderX** 打开 `yuxingu-Miniprogram-dev`
 2. 菜单：**发行 → 小程序-微信**
@@ -224,19 +410,19 @@ npx uni build -p mp-weixin
 
 编译产物目录：`unpackage/dist/build/mp-weixin/`（或 dev 目录）
 
-### 5.2 微信开发者工具
+### 7.2 微信开发者工具
 
 1. 导入上述 `mp-weixin` 目录
 2. AppID：`wx6782dd88e655f1a7`（见 `manifest.json`）
 3. 预览 / 真机调试
 
-### 5.3 上传体验版 / 正式版
+### 7.3 上传体验版 / 正式版
 
 1. 开发者工具 → **上传**
 2. 登录 [微信公众平台](https://mp.weixin.qq.com/) → **管理 → 版本管理**
 3. 将上传版本设为 **体验版** 供内部验收，或提交审核后发布
 
-### 5.4 发布前检查（小程序侧）
+### 7.4 发布前检查（小程序侧）
 
 - [ ] `util/yxgConfig.js` 中 H5 地址为生产域名
 - [ ] `util/requestConfig.js` 中 Java API 仍为 `https://miniapp.yuxingu.com.cn`
@@ -245,9 +431,28 @@ npx uni build -p mp-weixin
 
 ---
 
-## 6. 上线验证清单
+## 8. Ubuntu 一键部署顺序（Checklist）
 
-### 6.1 服务端
+按顺序执行，避免愈心魔方 Tab 白屏：
+
+```text
+□ 1. MySQL + Java（miniapp）已运行 — 无需本说明改动
+□ 2. 安装 PostgreSQL（§3.1 或 §3.2），建库 yuxingu
+□ 3. 拉取 digital-psychology，构建 yuxingu-api（§4）
+□ 4. 编写 config.local.yaml（database 指向 PostgreSQL:5432）
+□ 5. systemctl start yuxingu-api，curl healthz 通
+□ 6. 本机 npm run build:h5，rsync 到 /var/www/yuxingu-h5/psy/
+□ 7. 配置 Nginx（§5.3），reload，curl https://h5.../psy/api/v1/healthz
+□ 8. 浏览器打开 https://h5.yuxingu.com.cn/psy/?mp=1，确认备案号与页面
+□ 9. HBuilderX 发行小程序，上传体验版
+□ 10. 真机：愈心魔方 Tab + 咨询/测评 Tab 均正常
+```
+
+---
+
+## 9. 上线验证清单
+
+### 9.1 服务端
 
 ```bash
 # H5 首页
@@ -260,7 +465,7 @@ curl -sS https://h5.yuxingu.com.cn/psy/api/v1/healthz
 curl -I 'https://h5.yuxingu.com.cn/psy/?mp=1'
 ```
 
-### 6.2 微信开发者工具 / 真机
+### 9.2 微信开发者工具 / 真机
 
 | 步骤 | 预期 |
 |------|------|
@@ -271,20 +476,22 @@ curl -I 'https://h5.yuxingu.com.cn/psy/?mp=1'
 | 咨询 / 测评 Tab | 仍走 miniapp 旧接口，登录与订单正常 |
 | 未登录访问需登录能力 | 弹出微信手机号登录 |
 
-### 6.3 常见故障
+### 9.3 常见故障
 
 | 现象 | 原因 | 处理 |
 |------|------|------|
 | WebView 白屏 | 业务域名未配或校验文件缺失 | 微信后台 → 业务域名 → 重新校验 |
 | H5 内接口失败 | request 合法域名缺 `h5.yuxingu.com.cn` | 补充合法域名，等 5 分钟生效 |
 | 404 on `/psy/ask` 刷新 | Nginx 未配 SPA fallback | 确认 `try_files` 指向 `/psy/index.html` |
-| API 502 | Go 未启动或反代路径错误 | 查 `yuxingu-api` 日志与 `proxy_pass` |
+| API 502 | Go 未启动或反代路径错误 | 查 `journalctl -u yuxingu-api` 与 Nginx `proxy_pass` |
+| API 连库失败 | 误配 MySQL 或 PG 密码/端口错 | `database` 必须 PostgreSQL；`psql` 自测 |
 | H5 仍显示底栏 | 未带 `mp=1` | 检查 `yxgConfig.js` 与 WebView URL |
 | 双层底栏 | H5 未进 embed 模式 | 确认 URL 含 `?mp=1` 且已部署最新 H5 |
+| 迁移失败 | PG 权限不足 | `GRANT ALL ON DATABASE yuxingu TO yuxingu` |
 
 ---
 
-## 7. 更新与回滚
+## 10. 更新与回滚
 
 ### 仅更新愈心魔方（H5 + API）
 
@@ -312,7 +519,7 @@ sudo systemctl restart yuxingu-api
 
 ---
 
-## 8. 仓库与路径速查
+## 11. 仓库与路径速查
 
 | 内容 | 路径 |
 |------|------|
@@ -323,9 +530,12 @@ sudo systemctl restart yuxingu-api
 | H5 构建命令 | `digital-psychology` 根目录 `npm run build:h5` |
 | 本地开发 | Go：`cd apps/api && go run ./cmd/server`；H5：`npm run dev:h5` |
 
+| ICP 常量 | `packages/utils/src/icp.ts` |
+| 部署本文 | `docs/DEPLOY-MINI-PROGRAM-H5.md` |
+
 ---
 
-## 9. 后续（非展示期）
+## 12. 后续（非展示期）
 
 - 微信登录与 Go Auth 统一（单账号）
 - Java 顾问/测评域逐步迁入 Go API