huangjingfen/docs/project-shaoyaoju/deploy-syj.md

# syj 商城变体部署手册

少药局线上站点：`https://syj.fsgx.cn`

一键发布脚本：`pro_v3.5.1/deploy/release-syj.sh`

发布方式：本地当前分支构建 admin → 同步 `public/admin/` 和后端代码 → 远端切换 `.env-syj` → `php think clear` → Swoole reload → 健康检查 → 失败自动回滚。

覆盖范围：
- 后端 PHP 代码
- admin 前端构建产物 `public/admin/`
- 远端 `.env` 使用 `.env-syj`
- Swoole 平滑 reload
- 远端备份与回滚

不覆盖：
- `view/uniapp_v2/` 小程序端，需要 HBuilderX / 微信开发者工具单独发布
- `view/uniapp/`
- Composer 依赖安装
- 数据库结构迁移和配置项插入

---

## 1. 本次上线

本次已推送分支：`syj-bypass-auth`

本次提交：

```bash
673a19b3 feat: add channel code integral reward
```

主要内容：
- `admin/agent/agent_manage/index` 增加“小程序推广码”列，并将“推广用户数量”移动到“小程序推广码”后面。
- 积分配置新表单增加：
  - 渠道码积分奖励
  - 渠道分销员UID
  - 渠道码奖励积分
- 新用户扫描指定分销员小程序分享二维码注册后，可按配置发放积分，仅新用户注册事件触发，且通过积分账单防重复。
- 修复 `/admin/system/maintain/clear/index` 清除缓存、清除日志在目录不存在时可能报错的问题。

上线命令：

```bash
cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
git fetch origin
git checkout syj-bypass-auth
git pull --ff-only origin syj-bypass-auth
bash deploy/release-syj.sh
```

如果确认 admin 已经构建过，可跳过构建：

```bash
bash deploy/release-syj.sh --skip-build
```

---

## 2. 发布前检查

```bash
cd /Users/mac/scott2026/huangjingfen
git branch --show-current
git log -1 --oneline
git status --short
```

正常应在：

```bash
syj-bypass-auth
```

确认远端可访问：

```bash
ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && pwd && php -v | head -1'
curl -ksS -o /dev/null -w "api/version -> %{http_code}\n" https://syj.fsgx.cn/api/version
curl -ksS -o /dev/null -w "admin -> %{http_code}\n" https://syj.fsgx.cn/admin/
```

确认本次代码在本地：

```bash
rg -n "channel_code_integral_status|channel_code_agent_uid|channel_code_give_integral" \
  pro_v3.5.1/app/services/system/config/SystemConfigServices.php \
  pro_v3.5.1/app/listener/user/Register.php

rg -n "小程序推广码|推广用户数量|showXcxCode" \
  pro_v3.5.1/view/admin/src/pages/agent/agentManage.vue
```

---

## 3. 数据库配置项

发布脚本不会自动写数据库。上线前确认 `eb_system_config` 已存在以下配置项，并归属积分配置分组 `config_tab_id = 11`。

查询：

```bash
mysql -h8.140.50.89 -P3306 -usyj-shop -p syj-shop -e "
SELECT menu_name, config_tab_id, type, input_type, info, value, \`desc\`, parameter, sort, status
FROM eb_system_config
WHERE menu_name IN (
  'channel_code_integral_status',
  'channel_code_agent_uid',
  'channel_code_give_integral'
);"
```

缺失时插入：

```sql
INSERT INTO eb_system_config
  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
SELECT 11, 'channel_code_integral_status', 'radio', '', '', '1=>开启\n0=>关闭', 0, '', 0, 0, '0',
       '渠道码积分奖励',
       '开启后，新用户扫描指定分销员的小程序分享二维码注册可获得积分奖励，仅限新用户领取一次',
       7, 1
WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_integral_status');

INSERT INTO eb_system_config
  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
SELECT 11, 'channel_code_agent_uid', 'text', 'number', '', '', 0, '', 0, 0, '0',
       '渠道分销员UID',
       '填写分销员UID；该分销员的小程序推广二维码将作为渠道码',
       6, 1
WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_agent_uid');

INSERT INTO eb_system_config
  (config_tab_id, menu_name, type, input_type, config_tab, parameter, upload_type, required, width, high, value, info, `desc`, sort, status)
SELECT 11, 'channel_code_give_integral', 'text', 'number', '', '', 0, '', 0, 0, '0',
       '渠道码奖励积分',
       '新用户扫描渠道码注册后获得的积分数量；设置为0则不发放',
       5, 1
WHERE NOT EXISTS (SELECT 1 FROM eb_system_config WHERE menu_name = 'channel_code_give_integral');
```

后台配置路径：

```text
admin/marketing/integral/system_config/3/11
```

配置说明：
- `渠道码积分奖励`：开启后生效。
- `渠道分销员UID`：填写作为渠道码来源的分销员 UID。
- `渠道码奖励积分`：新用户扫描该分销员小程序推广码注册后获得的积分数。

---

## 4. 日常发布

```bash
cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
bash deploy/release-syj.sh
```

脚本阶段：
1. `Pre-flight checks`：校验分支、`.env-syj`、远端目录、admin 生产 API 地址。
2. `Build admin`：在 `view/admin` 执行 `npm run build`。
3. `Sync admin dist -> public/admin/`：把 `view/admin/dist/` 同步到 `public/admin/`。
4. `Release tag`：生成 `YYYYMMDD-HHMMSS-<git sha>`。
5. `rsync`：同步项目到 `/www/wwwroot/syj.fsgx.cn`，旧文件备份到 `/www/wwwroot/syj.fsgx.cn-bak/<tag>/`。
6. `Remote`：远端 `.env-syj` 覆盖 `.env`，执行 `php think clear`，reload Swoole。
7. `Healthcheck`：检查 `https://syj.fsgx.cn/api/version` 和 `https://syj.fsgx.cn/admin/`。
8. 成功后写入本地 `pro_v3.5.1/deploy/.last-release`。

可选参数：
- `--dry-run`：只预览 rsync 改动，不改远端。
- `--skip-build`：复用已有 `view/admin/dist/`。
- `--rollback <tag>`：回滚指定备份。

---

## 5. 上线后验收

基础健康：

```bash
curl -ksS -o /dev/null -w "api/version -> %{http_code}\n" https://syj.fsgx.cn/api/version
curl -ksS -o /dev/null -w "admin -> %{http_code}\n" https://syj.fsgx.cn/admin/
```

远端代码确认：

```bash
ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && \
grep -n "channel_code_integral_status" app/services/system/config/SystemConfigServices.php && \
grep -n "giveChannelCodeIntegral" app/listener/user/Register.php && \
grep -n "小程序推广码" view/admin/src/pages/agent/agentManage.vue public/admin/js/*.js 2>/dev/null | head'
```

后台页面验收：
- `admin/marketing/integral/system_config/3/11` 能看到 3 个渠道码积分配置项。
- `admin/agent/agent_manage/index` 列顺序为：`小程序推广码` → `推广用户数量` → `上级推广人`。
- 点击“小程序推广码”的“查看”能打开二维码弹窗。
- `/admin/system/maintain/clear/index` 清除缓存、清除日志不再报错。

业务验收：
1. 在积分配置页开启“渠道码积分奖励”。
2. 设置“渠道分销员UID”和“渠道码奖励积分”。
3. 使用该分销员的小程序推广码新注册用户。
4. 新用户积分增加对应数量。
5. `eb_user_bill` 中出现 `type = channel_code_add` 的积分账单。
6. 同一用户不会重复领取。

查询账单：

```sql
SELECT uid, category, type, title, number, balance, mark, add_time
FROM eb_user_bill
WHERE type = 'channel_code_add'
ORDER BY id DESC
LIMIT 20;
```

---

## 6. 回滚

查看最近备份：

```bash
ssh root@8.140.50.89 'ls -1t /www/wwwroot/syj.fsgx.cn-bak | head -10'
```

执行回滚：

```bash
cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
bash deploy/release-syj.sh --rollback 20260521-005301-673a19b3
```

说明：
- `.env` 不在回滚范围内，避免误覆盖运行环境。
- 数据库配置项和业务数据不随脚本回滚。
- 若本次上线已经产生积分账单，代码回滚不会自动撤销账单，需要业务人工处理。

---

## 7. 故障排查

| 现象 | 排查 |
|------|------|
| 后台看不到新增配置项 | 确认远端代码已更新、Swoole 已 reload、`eb_system_config` 三条配置存在且 `config_tab_id = 11` |
| admin 页面还是旧列顺序 | 确认 `public/admin/` 是最新构建产物，浏览器强刷或清缓存 |
| 新用户未获得积分 | 检查配置是否开启、分销员 UID 是否正确、扫码二维码是否 `third_type = spread_routine` |
| 重复发积分 | 查询 `eb_user_bill.type = channel_code_add`，代码按用户已有该账单防重复 |
| 清缓存/清日志失败 | 看 `runtime/log/` 和 `app/services/system/log/ClearServices.php` 是否已更新 |
| `/api/version` 不是 200 | 看 Swoole 是否运行、Nginx 反代、ThinkPHP 日志 |
| reload 后代码未生效 | 宝塔 Supervisor 兜底：`/www/server/panel/pyenv/bin/supervisorctl restart pro3.5.1:pro3.5.1_00` |
| rsync 提示 `.user.ini` | `deploy/rsync-exclude.txt` 已排除 `public/.user.ini`，不需要删除远端文件 |

远端常用命令：

```bash
ssh root@8.140.50.89 'cd /www/wwwroot/syj.fsgx.cn && php think clear'
ssh root@8.140.50.89 'ps aux | grep "php think swoole" | grep -v grep'
ssh root@8.140.50.89 'tail -100 /www/wwwroot/syj.fsgx.cn/runtime/swoole/swoole.log'
ssh root@8.140.50.89 'tail -100 /www/server/panel/plugin/supervisor/log/pro3.5.1.out.log'
```

---

## 8. 本机环境

启动本机后端和 admin：

```bash
cd /Users/mac/scott2026/huangjingfen/pro_v3.5.1
bash deploy/start-local-syj.sh start
```

常用命令：

```bash
bash deploy/start-local-syj.sh status
bash deploy/start-local-syj.sh restart
bash deploy/start-local-syj.sh logs
bash deploy/start-local-syj.sh stop
```

本机地址：
- 后端：`http://127.0.0.1:20199`
- admin：`http://localhost:8085/admin/`

注意：
- `view/admin/.env.dev` 需要指向 `http://127.0.0.1:20199/adminapi` 才会请求本机后端。
- `view/uniapp_v2/` 不由本脚本启动。

---

## 9. 服务器留档

路径：
- 项目：`/www/wwwroot/syj.fsgx.cn/`
- 备份：`/www/wwwroot/syj.fsgx.cn-bak/`
- Swoole 日志：`/www/wwwroot/syj.fsgx.cn/runtime/swoole/swoole.log`
- Supervisor 日志：`/www/server/panel/plugin/supervisor/log/pro3.5.1.out.log`
- ThinkPHP 日志：`/www/wwwroot/syj.fsgx.cn/runtime/log/`

Nginx 要点：
- `/admin/` 指向 `public/admin/`
- `/api/`、`/adminapi/` 由 Swoole 处理
- Swoole 监听端口：`20199`

`.env-syj`：
- `[DATABASE]` 指向 `8.140.50.89`
- `[REDIS]` 指向 `8.140.50.89`
- 生产建议 `APP_DEBUG = false`，当前脚本不会强制改该值