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

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

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

---

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：

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 服务器

• 一台可跑 Nginx + Go 二进制（或容器）的 VPS
• PostgreSQL（Go API 用；可与现有库同机或托管）
• Java 微服务 + miniapp.yuxingu.com.cn 保持现有部署，本说明不覆盖

---

3. Go API 部署

仓库：digital-psychology

3.1 构建

cd /path/to/digital-psychology/apps/api
go test ./...
go build -o yuxingu-api ./cmd/server

3.2 配置

cp config.example.yaml config.local.yaml
# 编辑 config.local.yaml：database、deepseek.api_key（Ask 需要）等

生产环境建议用环境变量覆盖敏感项，勿把密钥提交 Git。

3.3 数据库迁移

API 启动时会自动应用 apps/api/migrations/。首次部署前确保 PostgreSQL 已创建库和用户。

# 本地仅 DB 示例
cd /path/to/digital-psychology
docker compose -f docker-compose.dev.yml up -d

3.4 运行（示例 systemd）

# /etc/systemd/system/yuxingu-api.service
[Unit]
Description=Yuxingu Go API
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/yuxingu/apps/api
ExecStart=/opt/yuxingu/apps/api/yuxingu-api
Environment=APP_ENV=prod
Restart=on-failure

[Install]
WantedBy=multi-user.target

API 默认监听 :8080（见 config.local.yaml 的 http_addr）。

3.5 健康检查

curl -sS http://127.0.0.1:8080/api/v1/healthz
# 期望：{"code":0,"data":{...}}

---

4. H5 构建与 Nginx 部署

4.1 构建静态资源

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

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

4.2 上传到服务器

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

目录结构示例：

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

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

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：

sudo nginx -t && sudo systemctl reload nginx

4.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. 微信小程序部署

仓库：yuxingu-Miniprogram-dev

5.1 开发工具构建

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

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

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

5.2 微信开发者工具

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

5.3 上传体验版 / 正式版

1. 开发者工具 → 上传
2. 登录 微信公众平台 → 管理 → 版本管理
3. 将上传版本设为 体验版 供内部验收，或提交审核后发布

5.4 发布前检查（小程序侧）

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

---

6. 上线验证清单

6.1 服务端

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

6.2 微信开发者工具 / 真机

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

6.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
H5 仍显示底栏	未带 mp=1	检查 yxgConfig.js 与 WebView URL
双层底栏	H5 未进 embed 模式	确认 URL 含 ?mp=1 且已部署最新 H5

---

7. 更新与回滚

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

# 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 旧二进制
• 小程序：版本管理 → 回退到上一审核版本

---

8. 仓库与路径速查

内容	路径
小程序 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

---

9. 后续（非展示期）

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