# 旺财AI 部署说明文档

> 版本：v1.4.4 ｜ 更新日期：2026-09-16
> 配套交付物见同目录《旺财AI_接口说明文档.md》

---

## 0. 交付物清单

```
release/
├── android/                                   ← 安卓安装包
│   ├── wangcai-ai-v1.4.4.apk               ← 正式包：纯功能空壳，数据全走后端（上架/真实使用用这个）
│   └── wangcai-ai-v1.4.4-demo.apk          ← 演示包：内置演示数据，无后端也能跑（内部演示用）
├── ios/
│   └── IOS构建说明.md                          ← iOS 工程已就绪，需 Mac 环境构建（内含完整步骤）
├── admin/
│   └── admin.html                             ← 管理后台单页（已内置于后端 jar，通常无需单独部署）
├── server/                                    ← 后端服务器部署包
│   ├── wangcai-backend-0.1.0-SNAPSHOT.jar     ← 可执行 fat jar（JDK 17）
│   ├── start-windows.bat                      ← Windows 一键启动
│   ├── start-linux.sh                         ← Linux/macOS 一键启动
│   └── （生产 MySQL / 环境变量配置见本文档第 2 节）
├── 旺财AI_接口说明文档.md
└── 旺财AI_部署说明文档.md                      ← 本文档
```

---

## 1. 后端服务器部署

### 1.1 环境要求

| 项 | 要求 |
|---|---|
| JDK | **17**（必须，Temurin/Oracle 均可）|
| 内存 | ≥ 1GB 空闲（H2 演示档）；MySQL 生产建议 2GB+ |
| 端口 | 8081（演示）/ 8080（生产默认），可用 `SERVER_PORT` 改 |
| 数据库 | 演示档无需数据库；生产需 MySQL 5.7+/8.0 |

### 1.2 演示档部署（最快，3 分钟）

H2 内存库 + 种子数据，无需装 MySQL，适合 POC/联调。

**Windows：**
```bat
cd release\server
start-windows.bat          :: 默认 8081；或 start-windows.bat 传入端口前先 set SERVER_PORT=9090
```

**Linux / macOS：**
```bash
cd release/server
chmod +x start-linux.sh
./start-linux.sh 8081              # 前台运行
# 生产常驻：
nohup ./start-linux.sh 8081 > backend.log 2>&1 &
```

**验证部署成功：**
```bash
curl http://127.0.0.1:8081/api/health
# 期望: {"code":0,"message":"ok","data":{"status":"UP",...}}

curl -I http://127.0.0.1:8081/admin.html
# 期望: HTTP/1.1 200
```

### 1.3 演示档注意事项（必读）

1. **H2 是内存库：重启后端 = 清空全部数据**。更严重的是 **已登录用户的 token 全部失效**——App 端会表现为"列表全空且无提示"（已知体验缺陷，待修复为自动重登）。重启后端后，所有用户需重新登录。
2. 演示验证码固定 `123456`，任意 `1xxxxxxxxxx` 手机号可登录。
3. 演示档只用于联调/POC，**不要**用演示档接真实用户。

### 1.4 生产部署（MySQL + 环境变量）

默认 profile 使用 MySQL（库表结构启动时自动建，幂等）。

```bash
# 1. 准备 MySQL：建库
mysql> CREATE DATABASE wangcai DEFAULT CHARACTER SET utf8mb4;

# 2. 以环境变量注入配置（不要改 jar 内配置文件）
export SERVER_PORT=8080
export MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_DB=wangcai
export MYSQL_USER=wangcai MYSQL_PASSWORD='强密码'
export JWT_SECRET='随机≥32字节字符串'          # 必改！默认值仅供开发
export AUTH_DEBUG_CODE=false                   # 关闭演示验证码
export WALLET_DEMO_RECHARGE=false              # 关闭演示充值
export WANGCAI_ADMIN_TOKEN='后台口令'          # 强烈建议：管理接口加 X-Admin-Token 校验
export CORS_ALLOWED_ORIGINS='https://admin.yourdomain.com'   # 管理后台跨域白名单

# 四家接入点 Key（App 里选哪家模型就走哪家；不配的自动回退默认接入点，不影响使用）
export WC_AI_QWEN_API_KEY='sk-...'             # 千问 · 阿里云百炼
export WC_AI_DOUBAO_API_KEY='...'              # 豆包 · 火山方舟（或填 ep- 接入点 ID 到 MODEL）
export WC_AI_HUNYUAN_API_KEY='sk-...'          # 元宝 · 腾讯云混元
export WC_AI_DEEPSEEK_API_KEY='sk-...'         # DeepSeek 开放平台
# 可选：默认接入点（四家都没配时的兜底；也可只配一家快速上线）
export WC_AI_API_KEY="$WC_AI_DEEPSEEK_API_KEY"
export WC_AI_BASE_URL='https://api.deepseek.com'
export WC_AI_MODEL='deepseek-v4-flash'

# 3. 启动（注意：不带 --spring.profiles.active=demo）
java -jar wangcai-backend-0.1.0-SNAPSHOT.jar
```

**全部环境变量速查：**

| 变量 | 默认 | 说明 |
|---|---|---|
| `SERVER_PORT` | 8080 | HTTP 端口 |
| `MYSQL_HOST/PORT/DB/USER/PASSWORD` | 127.0.0.1/3306/wangcai/root/root | MySQL 连接 |
| `JWT_SECRET` | 开发默认值 | **生产必改**，≥32 字节 |
| `JWT_EXPIRE_HOURS` | 168 | 登录态有效期（小时）|
| `AUTH_DEBUG_CODE` | true | 演示验证码开关，生产置 false |
| `WALLET_DEMO_RECHARGE` | true | 演示充值开关，生产置 false |
| `WANGCAI_ADMIN_TOKEN` | 空 | 管理接口口令，空=不校验 |
| `CORS_ALLOWED_ORIGINS` | localhost,127.0.0.1 | 跨域白名单 |
| `WC_AI_REMOTE_ENABLED` | true | 远程大模型总开关 |
| `WC_AI_API_KEY` / `WC_AI_BASE_URL` / `WC_AI_MODEL` | 空 / `https://api.deepseek.com` / `deepseek-v4-flash` | 默认接入点（兜底）|
| `WC_AI_QWEN_API_KEY` / `_BASE_URL` / `_MODEL` | 空 / 百炼 compatible-mode / `qwen3.7-max` | 千问接入点 |
| `WC_AI_DOUBAO_API_KEY` / `_BASE_URL` / `_MODEL` | 空 / 方舟 api/v3 / `doubao-seed-2-1-pro-260628` | 豆包接入点 |
| `WC_AI_HUNYUAN_API_KEY` / `_BASE_URL` / `_MODEL` | 空 / 混元 v1 / `hy3` | 元宝（混元）接入点 |
| `WC_AI_DEEPSEEK_API_KEY` / `_BASE_URL` / `_MODEL` | 空 / `https://api.deepseek.com` / `deepseek-v4-flash` | DeepSeek 接入点 |

### 1.4.1 四家接入点对照 ⭐

四家都为 **OpenAI 兼容协议**（`{base_url} + /chat/completions`），填好 Key 即生效，
**不需要改代码、不需要改 App**。App 里选哪个模型，后端就按该模型的 `scope` 路由到对应接入点。

| 模型（App 展示） | scope | 厂商 / 平台 | base_url | 模型名示例 |
|---|---|---|---|---|
| 元宝 | `HUNYUAN` | 腾讯云 | `https://api.hunyuan.cloud.tencent.com/v1` | `hy3` / `hunyuan-turbos-latest` |
| 豆包 | `DOUBAO` | 火山方舟 | `https://ark.cn-beijing.volces.com/api/v3` | `doubao-seed-2-1-pro-260628`，或填接入点 ID（`ep-` 开头）|
| 千问 | `QWEN` | 阿里云百炼 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.7-max` / `qwen-plus` |
| DeepSeek | `DEEPSEEK` | DeepSeek 开放平台 | `https://api.deepseek.com` | `deepseek-v4-flash` / `deepseek-v4-pro` |

> **表格顺序即 App 内展示顺序**（元宝 → 豆包 → 千问 → DeepSeek），由模型表
> `wc_ai_model.sort_no` 决定；后台「AI 模型」页改排序号即可调整，App 下次拉取生效。

**验证配置是否生效**（Key 会脱敏返回）：

```bash
curl -s http://127.0.0.1:8080/api/ai/providers
# 看对应 scope 的 "ready": true 即表示该接入点已就绪
```

**回退链**（任何一环失败都不会让用户拿不到回答）：

```
所选模型接入点（providers.<scope>，需配 Key）
   ↓ 未配 Key / 调用失败
默认接入点（WC_AI_API_KEY，全局兜底）
   ↓ 也未配
本地规则引擎（离线可用，回答来自内置模板）
```

响应里的 `provider` 字段会如实告知本次回答实际来自哪家（如 `阿里云百炼` / `本地引擎`），
便于线上排查「到底走没走大模型」。

> **只上线一家也行**：只填 `WC_AI_API_KEY`（默认接入点），四个模型都会走这一家；
> 后续逐个补齐厂商 Key 即可，无需发版。

> **模型清单由后台维护**：App「问一问」的模型选择栏来自 `/api/ai/models`，
> 在管理后台「AI 模型」页新增/改名/上下架/排序后，App 下次进入即生效。
> 新增模型时把 `scope` 填成对应的路由键，它就会走该厂商接入点并扣该维度 token。

### 1.5 systemd / Docker 常驻（Linux 生产推荐）

交付包内已含现成文件：

- `server/wangcai-backend.service`：systemd 单元，复制到 `/etc/systemd/system/` 后按需改环境变量：
  ```bash
  cp wangcai-backend.service /etc/systemd/system/
  systemctl daemon-reload && systemctl enable --now wangcai
  ```
- `server/Dockerfile` + `server/docker-compose.yml`：容器化部署（compose 里含本地 MySQL 8）：
  ```bash
  cd server && docker compose up -d
  ```

---

## 2. 管理后台部署

### 2.1 方式 A：随 jar 内置（推荐，零配置）✅

`admin.html` 已打包进 jar 的静态资源，**部署后端即自动可用**：

```
http://<服务器IP>:8081/admin.html
登录工号：ops01（演示内置）
```

- 所有 `/api/admin/**` 请求自动带 `X-Admin-User` 头（同源，无 CORS 问题）。
- 配置了 `WANGCAI_ADMIN_TOKEN` 后，登录页需输入口令。

**左导航「AI 模型」页**（本次新增）用于维护 App「问一问」的模型选择栏：
新增 / 改名 / 换图标 / 改厂商 / **↑↓ 调排序** / 上下架 / 删除，并可一键查看四家接入点状态（Key 脱敏）。
模型选择栏和技能选择栏都由此类后台数据驱动，**调整不需要 App 发版**。

> **顺序 = 默认**。模型列表里**第一台上架模型**就是用户打开「问一问」时默认高亮选中的那个
> （也是不手动切换时实际调用的模型）。用每行的「↑ / ↓」把它移到第一位即可改变默认项 ——
> 后台列表里该行会带「默认」标记。列表越靠前，App 里越靠左。

### 2.2 方式 B：独立域名部署（Nginx 反代）

适合后台需要独立域名/HTTPS 的场景。**注意 admin.html 用相对路径请求 `/api/**`，必须反代同源**：

```nginx
server {
    listen 443 ssl;
    server_name admin.yourdomain.com;

    # 管理后台静态页
    location / {
        root /opt/wangcai-admin;
        index admin.html;
    }

    # API 反代到后端（保持同源，避免 CORS）
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```
把 `release/admin/admin.html` 放到 `/opt/wangcai-admin/`，并在后端配置
`CORS_ALLOWED_ORIGINS=https://admin.yourdomain.com`（双保险）。

### 2.3 管理后台权限说明

- 普通工号（ops01）：可看数据、内容审核、短视频审核、技能审核。
- **用户封禁 / 调余额 / 关订单**：普通工号调用返回 **403**，需走「高管审批」：创建审批单 → 高管工号 review 通过后生效。
- 生产建议配置 `WANGCAI_ADMIN_TOKEN`，防止仅凭工号即可调用。

---

## 3. 安卓 App 安装

### 3.1 正式包（上架/真实用户）

```
release/android/wangcai-ai-v1.4.4.apk   （约 87.5 MB）
```

- **包内只有功能、没有任何演示数据**；所有业务数据登录后从后端接口拉取。
- 默认后端地址 `http://127.0.0.1:8081`。真机直连部署服务器时，安装时无需改包，但**必须保证手机能访问后端**：
  - USB 联调：`adb reverse tcp:8081 tcp:8081`（把手机的 127.0.0.1:8081 映射到电脑）
  - 局域网/公网：需重新打包，注入正式地址：
    ```bash
    flutter build apk --release \
      --dart-define=API_BASE_URL=https://api.yourdomain.com
    ```
- ⚠️ 生产后端必须 **HTTPS**（App 已禁用明文 HTTP，仅 localhost/127.0.0.1/10.0.2.2 例外用于开发）。

### 3.2 演示包（内部演示，无后端）

```
release/android/wangcai-ai-v1.4.4-demo.apk
```
内置演示数据（帖子/商品/技能/短视频等），不连后端即可演示完整交互。

### 3.3 安装与登录步骤

1. 手机安装 APK（允许未知来源，或用 `adb install xxx.apk`）。
2. 打开 App → 跳过引导 → 登录页输入手机号（演示后端：任意 `1xxxxxxxxxx`）→ 获取验证码 → 输入 `123456` → 勾选协议 → 登录。
3. 登录后各 Tab 自动从后端拉数据。

### 3.4 常见问题

| 现象 | 原因与解决 |
|---|---|
| 列表全空、无提示 | ① token 失效（后端重启过）→ 退出重登；② 手机连不上后端 → 检查 `adb reverse` / 网络 / 防火墙 |
| 提示"暂时联系不上旺财服务" | 后端没起 / 地址不通，先 `curl http://<host>:8081/api/health` |
| 安装报签名冲突 | 手机上有旧签名版本 → 先卸载旧版再装 |
| USB 联调时 App 连不上本机后端 | `adb reverse tcp:8081 tcp:8081`（adb 服务重启后需重建）|

---

## 4. iOS App 构建

见 `release/ios/IOS构建说明.md`。要点：
- **Windows 环境无法出 .ipa**，需 macOS + Xcode + Apple 开发者账号；
- Flutter iOS 工程（`wangcai-app/ios/`）已就绪，Mac 上 `flutter build ipa --dart-define=API_BASE_URL=...` 即可；
- 上架包同样使用"纯功能空壳"模式（不加 EMBED_DEMO_DATA）。

---

## 5. 安全检查清单（上线前）

- [ ] `JWT_SECRET` 已更换为随机值
- [ ] `AUTH_DEBUG_CODE=false`（关闭演示验证码 123456）
- [ ] `WALLET_DEMO_RECHARGE=false`
- [ ] `WANGCAI_ADMIN_TOKEN` 已设置（管理接口二次加固）
- [ ] 管理后台仅内网/VPN 可达，或已配置独立域名 + HTTPS
- [ ] 生产数据库为 MySQL（非 H2 内存库）
- [ ] App 正式包注入了 HTTPS 的 `API_BASE_URL`
- [ ] 短视频媒体改为后端/CDN URL 下发（当前 `assetKey` 映射端内素材，见下）

## 6. 已知待办（不影响当前功能，上线前建议处理）

| 项 | 说明 |
|---|---|
| 短视频媒体通路 | 后端 `wc_short_video.asset_key` 映射端内 `assets/videos/clip1-3.mp4`，新视频无法远程下发。需改为后端/CDN 直接返回 video URL |
| App 静默离线 | 收到 401「请先登录」时 App 未自动重新登录，表现为列表空。需改为自动 re-login + UI 提示 |
| 相机/相册权限 | 拍摄/选素材仍为占位功能，接真功能时再申请 `CAMERA`、`READ_MEDIA_IMAGES` 权限（提前申请会被应用商店质疑）|
| 签名密钥保管 | `wangcai-app/android/key.properties` + `wangcai-release.jks` 含密码，**务必备份到安全位置**；丢失将无法更新 App |

---

## 7. 版本变更记录

| 版本 | 日期 | 变更 |
|---|---|---|
| v1.4.4 | 2026-09-16 | **聊天详情页成员数据接通后端**：群聊成员头像区改为展示真实成员（`GET /api/chat/members`，按本人过滤，微信式不展示自己）；「群成员」快捷搜索格在真实群聊中正常出现；长按移出成员改为**调用后端踢人接口**（失败如实提示，不再本地假删）。已知限制：「+」邀请入群仍只在本机生效（后端暂无邀请入群接口）。后端无改动 |
| v1.4.3 | 2026-09-16 | **聊天详情页微信化**：参照微信重做聊天信息设置页（成员头像区 + 虚线「+」加人 / 长按移出、查找聊天内容、消息免打扰 / 置顶 / 提醒、设置当前聊天背景、清空聊天记录、投诉）；**新增「查找聊天内容」搜索页**（快速分类宫格 + 关键词全文搜索）；ChatSession 新增 reminder / chatBackground 持久化字段。后端无改动 |
| v1.4.2 | 2026-09-15 | IM 聊一聊微信式改造：会话唯一来源 `/api/chat/conversations`，未读/免打扰/置顶/删除/清空，聊天设置页 |
| v1.4.1 | 2026-09-15 | 模型默认选中修复、演示包同步 |
| v1.4.0 | 2026-09-15 | 模型目录后台化：`wc_ai_model` 表 + admin CRUD/排序，四厂商接入点路由 |
| v1.3.0 | 2026-09-14 | 数据外置：市场包零演示数据，`EMBED_DEMO_DATA` 开关 |
