digital-psychology/docs/DEPLOY-MINI-PROGRAM-H5.md

# 愈心谷小程序 + 愈心魔方 H5 部署说明

适用于：**微信小程序**（`yuxingu-Miniprogram-dev`）嵌入 **愈心魔方 H5**（`digital-psychology/apps/user-h5`）的展示期上线。

**本地联调（免每次改服务器）** → 见 [LOCAL-DEV-MINI-PROGRAM-H5.md](LOCAL-DEV-MINI-PROGRAM-H5.md) · `npm run dev:mp`

---

## 1. 架构

```
微信小程序（uni-app）
├── 首页 / 咨询 / 测评 / 我的  →  https://miniapp.yuxingu.com.cn  （Java，rp-server-psychic）
└── 愈心魔方 Tab / 首页入口      →  https://h5.yuxingu.com.cn/psy/?mp=1  （WebView）
                                      └── /psy/api/*  →  Go API（digital-psychology）
```

| 组件 | 仓库 | 域名 |
|------|------|------|
| 小程序客户端 | `yuxingu-Miniprogram-dev` | —（微信后台上传） |
| 愈心魔方 H5 | `digital-psychology/apps/user-h5` | `h5.yuxingu.com.cn` |
| Go API | `digital-psychology/apps/api` | 同域反代 `/psy/api/` |
| 旧业务 API | `rp-server-psychic`（独立部署） | `miniapp.yuxingu.com.cn` |

H5 地址配置在小程序 `util/yxgConfig.js`：

```js
export const YXG_H5_BASE = 'https://h5.yuxingu.com.cn/psy/'
export const YXG_H5_HOME_URL = `${YXG_H5_BASE}?mp=1`
```

---

## 2. 前置条件

### 2.1 域名与证书

| 域名 | 用途 | 要求 |
|------|------|------|
| `h5.yuxingu.com.cn` | H5 静态 + Go API 反代 | HTTPS、已备案 |
| `miniapp.yuxingu.com.cn` | 咨询/测评/登录（已有） | HTTPS |

### 2.2 微信小程序后台

路径：**开发 → 开发管理 → 开发设置**

| 配置项 | 域名 |
|--------|------|
| **业务域名**（WebView 必配） | `h5.yuxingu.com.cn`（需上传校验文件到站点根目录） |
| **request 合法域名** | `https://miniapp.yuxingu.com.cn`、`https://h5.yuxingu.com.cn` |
| uploadFile 合法域名 | `https://miniapp.yuxingu.com.cn`（维持现状） |
| downloadFile 合法域名 | `https://miniapp.yuxingu.com.cn`（维持现状） |
| socket 合法域名 | 无需配置 |

### 2.3 服务器（Ubuntu 典型）

| 软件 | 用途 | 端口 |
|------|------|------|
| **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. 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`

### 4.1 服务器目录建议

```bash
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
```

服务器若无 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
chmod 600 config.local.yaml
```

`config.local.yaml` 示例（**PostgreSQL，非 MySQL**）：

```yaml
app:
  env: prod
  http_addr: "127.0.0.1:8080"   # 仅本机，由 Nginx 反代对外

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
cd /opt/yuxingu/digital-psychology/apps/api
./yuxingu-api
# 看到监听 127.0.0.1:8080、迁移无报错即可 Ctrl+C，改 systemd 常驻
```

### 4.5 systemd 常驻

```ini
# /etc/systemd/system/yuxingu-api.service
[Unit]
Description=Yuxingu Go API (愈心魔方)
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=www-data
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
```

若 PostgreSQL 用 Docker 容器名 `yuxingu-pg`，将 `After=` 改为 `docker.service` 或去掉 PostgreSQL 依赖。

```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
# 期望：{"code":0,"data":{...}}
```

---

## 5. H5 构建与 Nginx 部署

### 5.1 构建静态资源

```bash
cd /path/to/digital-psychology
npm ci
npm run build:h5
# 产物：apps/user-h5/dist/
```

构建产物 `base` 为 `/psy/`，与线上路径一致，**无需改 `baseURL`**（客户端请求 `/psy/api/v1/...`）。

### 5.2 上传到服务器

```bash
rsync -avz --delete apps/user-h5/dist/ user@your-server:/var/www/yuxingu-h5/psy/
```

目录结构示例：

```
/var/www/yuxingu-h5/psy/
├── index.html
├── assets/
└── ...
```

### 5.3 Nginx 配置（推荐：H5 + API 同域）

```nginx
server {
    listen 443 ssl http2;
    server_name h5.yuxingu.com.cn;

    ssl_certificate     /etc/ssl/h5.yuxingu.com.cn/fullchain.pem;
    ssl_certificate_key /etc/ssl/h5.yuxingu.com.cn/privkey.pem;

    # 微信业务域名校验文件（按后台提示的文件名放置）
    location = /MP_verify_xxxx.txt {
        root /var/www/wechat-verify;
    }

    # user-h5 SPA（history 模式）
    location /psy/ {
        alias /var/www/yuxingu-h5/psy/;
        try_files $uri $uri/ /psy/index.html;
    }

    # Go API 反代：/psy/api/v1/* → :8080/api/v1/*
    location /psy/api/ {
        rewrite ^/psy/api/(.*)$ /api/$1 break;
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Ask 流式响应
        proxy_buffering off;
        proxy_read_timeout 120s;
    }

    location = / {
        return 301 https://$host/psy/;
    }
}
```

reload：

```bash
sudo nginx -t && sudo systemctl reload nginx
```

### 5.4 H5 embed 模式说明

小程序 WebView 打开 `https://h5.yuxingu.com.cn/psy/?mp=1` 时：

- H5 **隐藏底部 TabBar**（仅小程序底栏导航）
- 子页路由自动保留 `mp=1` 参数
- 子页显示顶部返回键，不显示 H5 主导航

浏览器直访 `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/` 应能在页面底部看到备案号。

---

## 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`

### 7.1 开发工具构建

1. 用 **HBuilderX** 打开 `yuxingu-Miniprogram-dev`
2. 菜单：**发行 → 小程序-微信**
3. 或使用 CLI（需已安装 `@dcloudio/uni-cli` 等依赖）：

```bash
cd /path/to/yuxingu-Miniprogram-dev
# 具体命令以 HBuilderX / uni-app 版本为准
npx uni build -p mp-weixin
```

编译产物目录：`unpackage/dist/build/mp-weixin/`（或 dev 目录）

### 7.2 微信开发者工具

1. 导入上述 `mp-weixin` 目录
2. AppID：`wx6782dd88e655f1a7`（见 `manifest.json`）
3. 预览 / 真机调试

### 7.3 上传体验版 / 正式版

1. 开发者工具 → **上传**
2. 登录 [微信公众平台](https://mp.weixin.qq.com/) → **管理 → 版本管理**
3. 将上传版本设为 **体验版** 供内部验收，或提交审核后发布

### 7.4 发布前检查（小程序侧）

- [ ] `util/yxgConfig.js` 中 H5 地址为生产域名
- [ ] `util/requestConfig.js` 中 Java API 仍为 `https://miniapp.yuxingu.com.cn`
- [ ] Tab 顺序：首页 | 愈心魔方 | 心理咨询 | 心理测评 | 我的
- [ ] `static/n-menu/mf-*.png` 图标已替换为正式稿（当前可为占位图）

---

## 8. Ubuntu 一键部署顺序（Checklist）

按顺序执行，避免愈心魔方 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 首页
curl -I https://h5.yuxingu.com.cn/psy/

# API 健康
curl -sS https://h5.yuxingu.com.cn/psy/api/v1/healthz

# embed 首页可访问
curl -I 'https://h5.yuxingu.com.cn/psy/?mp=1'
```

### 9.2 微信开发者工具 / 真机

| 步骤 | 预期 |
|------|------|
| 打开小程序首页 | Banner、愈心魔方紫色入口条、测评/咨询卡片正常 |
| 点击「愈心魔方」入口 | 切到第 2 个 Tab，加载 H5 |
| 点击底部「愈心魔方」Tab | 同上 |
| H5 内点九宫格进子页（如问答） | 无 H5 底栏，有返回键，接口正常 |
| 咨询 / 测评 Tab | 仍走 miniapp 旧接口，登录与订单正常 |
| 未登录访问需登录能力 | 弹出微信手机号登录 |

### 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 未启动或反代路径错误 | 查 `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` |

---

## 10. 更新与回滚

### 仅更新愈心魔方（H5 + API）

```bash
# 1. 构建 H5
cd digital-psychology && npm run build:h5
rsync -avz --delete apps/user-h5/dist/ user@server:/var/www/yuxingu-h5/psy/

# 2. 更新 API（需停服瞬间）
cd apps/api && go build -o yuxingu-api ./cmd/server
sudo systemctl restart yuxingu-api
```

小程序 **WebView 无缓存强制刷新**时，用户可能仍看到旧 H5；可在 URL 加版本 query（如 `?mp=1&v=20260824`）或在微信公众平台重新发布小程序。

### 仅更新小程序壳

重新 HBuilderX 发行 → 上传新版本。不影响 H5 与 API。

### 回滚

- H5：恢复 `/var/www/yuxingu-h5/psy/` 备份目录
- API：`systemctl restart` 旧二进制
- 小程序：版本管理 → 回退到上一审核版本

---

## 11. 仓库与路径速查

| 内容 | 路径 |
|------|------|
| 小程序 Tab / 首页入口 | `yuxingu-Miniprogram-dev/pages/yxg-magic/`、`pages/index/index.vue` |
| H5 地址常量 | `yuxingu-Miniprogram-dev/util/yxgConfig.js` |
| H5 embed 逻辑 | `digital-psychology/apps/user-h5/src/lib/mpEmbed.ts` |
| Go API | `digital-psychology/apps/api/cmd/server` |
| 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` |

---

## 12. 后续（非展示期）

- 微信登录与 Go Auth 统一（单账号）
- Java 顾问/测评域逐步迁入 Go API
- CI 镜像发布见 `.ai/deployment.md`、`deploy/README.md`