john
185 lines
6.6 KiB
Markdown
185 lines
6.6 KiB
Markdown
# 105 服务器变更规范
|
||
|
||
> **硬性约束：** `105`（`root@120.26.184.105`）是运行/入口层，**不是**源码真相所在处。
|
||
> **禁止** SSH 登录后直接修改业务代码、脚本或配置源码；所有变更必须来自本地仓库 commit 后的正式发布流程。
|
||
> 本规则适用于人工与 Agent，无“临时改一下”例外。
|
||
|
||
## 105 的角色
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 定位 | 云侧入口 / 代理 / 历史链路，不承担可写业务数据主存储 |
|
||
| H5 运行目录 | `/root/tkmind_go/ui/h5` |
|
||
| Plaza 运行目录 | `/root/tkmind_go/ui/plaza` |
|
||
| 数据真身 | 在 `103`（MindSpace、users、data 等），见 [103/105 升级记录](103-105-upgrade-runbook-2026-06-26.md) |
|
||
|
||
本地开发仓库是 `/Users/john/Project/Memind`；生产 runtime 发布目标是 `103`。
|
||
**105 上的文件是部署产物，不是编辑源。**
|
||
|
||
## 禁止事项
|
||
|
||
以下操作一律禁止：
|
||
|
||
1. **SSH 到 105 后直接改源码**
|
||
包括但不限于：`sed -i`、`vi`/`nano`、`echo >> file`、手工上传单个 `.mjs`/`.ts`/`.tsx` 覆盖。
|
||
2. **在 105 上改脚本后当作“已发布”**
|
||
例如直接改 `/root/tkmind_go/ui/h5/scripts/wechat-mp-menu.mjs` 而不经过本地 commit 与发布。
|
||
3. **把 105 当开发/调试环境**
|
||
不在 105 上跑本地开发命令、试改业务逻辑、临时 patch。
|
||
4. **绕过发布流程的“快捷修复”**
|
||
“为了快”不是 SSH 直改的理由；违规改动会在下次发布时被覆盖，且与 Git 历史脱节。
|
||
|
||
## 允许的操作（只读与受控运维）
|
||
|
||
在**不修改业务源码**的前提下，允许：
|
||
|
||
- 只读排查：`systemctl status`、`journalctl`、健康检查 `curl`、查看目录结构
|
||
- 按 runbook 重启服务（需有文档依据，且变更本身不是改代码）
|
||
- 在**发布已完成、脚本内容已与本地 commit 一致**后，执行受控同步命令（见下文「服务号菜单」）
|
||
|
||
## 代码变更的正确流程
|
||
|
||
```text
|
||
本地 test-memind 修改
|
||
→ 本地验证
|
||
→ Git commit（可追溯）
|
||
→ 按现行发布流程发布到目标环境（103 Portal runtime / 其他已文档化的入口）
|
||
→ 发布后健康检查与业务路径验收
|
||
```
|
||
|
||
相关规则入口：
|
||
|
||
- [标准化开发测试发布约束](../ENGINEERING_WORKFLOW_RULES.md)
|
||
- [生产发布规则](../PRODUCTION_RELEASE_RULES.md)
|
||
- [Portal 生产更新发布指南](release-deploy.md)
|
||
- [103/105 升级与角色划分](103-105-upgrade-runbook-2026-06-26.md)
|
||
|
||
**不要**使用已停用的 `rsync_to_server.sh` 或直接 rsync 到 `105` 作为常规发布手段（见 `PRODUCTION_RELEASE_RULES.md`）。
|
||
|
||
## 105 Portal runtime 发布
|
||
|
||
`105` 上当前 H5 由 `systemd` 服务 `goose-h5` 运行，真实目录是：
|
||
|
||
```text
|
||
/root/tkmind_go/ui/h5
|
||
```
|
||
|
||
发布 `105` 的 Portal / 微信服务号相关能力时，必须走 **runtime artifact**，不要直接发源码树：
|
||
|
||
```bash
|
||
cd /Users/john/Project/Memind
|
||
|
||
# 仅预演，不切换 live
|
||
bash scripts/release-portal-runtime-105.sh --dry-run
|
||
|
||
# 正式发布到 105
|
||
bash scripts/release-portal-runtime-105.sh --yes
|
||
```
|
||
|
||
### 这条发布链的关键规则
|
||
|
||
1. 本地先把 `server.mjs` 与 `mindspace-sandbox-mcp.mjs` 打成 runtime bundle，再连同 `dist/`、`public/`、`schema.sql`、启动脚本一起打包。
|
||
2. **不要**把本机 Mac 的 `node_modules` 直接打进包发到 `105`。
|
||
`105` 是 Linux，像 `@node-rs/argon2` 这类原生依赖会因为平台不匹配而启动失败。
|
||
3. `105` 的 runtime 包默认**不带** `node_modules`；切换前会在 `105` 本机执行：
|
||
|
||
```bash
|
||
npm install --omit=dev --no-package-lock
|
||
```
|
||
|
||
确保安装的是 Linux 可用依赖。
|
||
4. 发布时默认保留这些持久项，不覆盖：
|
||
- `.env`
|
||
- `MindSpace/`
|
||
- `data/`
|
||
- `users/`
|
||
- `logs/`
|
||
- `public/plaza-covers/`
|
||
5. 发布完成后必须验：
|
||
|
||
```bash
|
||
ssh root@120.26.184.105 '
|
||
systemctl is-active goose-h5
|
||
curl -sf http://127.0.0.1:8080/api/status
|
||
'
|
||
```
|
||
|
||
正确结果应为：
|
||
- `goose-h5` = `active`
|
||
- `/api/status` 返回 `ok`
|
||
|
||
### 禁止事项（105 runtime）
|
||
|
||
- 禁止把 `node_modules/` 从本机打包后直接发到 `105`
|
||
- 禁止在 `105` 直接改 `server.mjs` / `wechat-mp.mjs` / `scripts/wechat-mp-menu.mjs`
|
||
- 禁止跳过健康检查就宣称“已发布”
|
||
|
||
## 服务号底部菜单（`wechat-mp-menu.mjs`）
|
||
|
||
菜单名称与链接定义在本地：
|
||
|
||
```text
|
||
scripts/wechat-mp-menu.mjs
|
||
```
|
||
|
||
### 两层动作，不可混淆
|
||
|
||
| 步骤 | 做什么 | 在哪里做 |
|
||
|------|--------|----------|
|
||
| 1. 改菜单定义 | 修改 `MENU` 常量（如 `M广场` → `M发现`） | **仅本地仓库** |
|
||
| 2. 同步到微信 | 调用微信 `menu/create` API | 目标环境已发布后的机器上执行脚本 |
|
||
|
||
### 正确流程
|
||
|
||
```bash
|
||
# 1. 本地改 scripts/wechat-mp-menu.mjs
|
||
cd /Users/john/Project/Memind
|
||
# 编辑 MENU → 本地验证 → git commit
|
||
|
||
# 2. 随 Portal/H5 走正式发布到 103（或当前文档规定的目标机）
|
||
# 确保线上脚本内容与 commit 一致
|
||
|
||
# 3. 在已发布且含微信凭证的环境执行同步（不是改文件）
|
||
node scripts/wechat-mp-menu.mjs
|
||
|
||
# 仅查看将提交的菜单结构，不调 API：
|
||
node scripts/wechat-mp-menu.mjs --dry-run
|
||
```
|
||
|
||
### 禁止做法（反例）
|
||
|
||
```bash
|
||
# ❌ 禁止：SSH 到 105 直接 sed 改菜单脚本
|
||
ssh root@120.26.184.105 "sed -i \"s/M广场/M发现/\" /root/tkmind_go/ui/h5/scripts/wechat-mp-menu.mjs"
|
||
|
||
# ❌ 禁止：只改 105 上的文件、不 commit、不发布
|
||
# ❌ 禁止：Agent 在未走发布流程时自行 SSH 改 105 源码
|
||
```
|
||
|
||
说明：第 3 步「执行 `node scripts/wechat-mp-menu.mjs`」是**调用微信 API**，本身不修改业务源码；但必须先完成本地改码 + commit + 发布，保证线上脚本与仓库一致。
|
||
|
||
## 发布时不会被覆盖的内容（历史 rsync 场景）
|
||
|
||
若仍涉及旧目录同步，以下路径通常在 exclude 中，**但这不构成“可以在 105 上改源码”的理由**：
|
||
|
||
- `.env`（环境密钥与运行配置）
|
||
- `MindSpace/`（用户空间数据）
|
||
|
||
业务脚本与前端代码**不在** exclude 内，发布时会覆盖 105 上的直改内容。
|
||
|
||
## Agent 执行清单
|
||
|
||
接到“改 105 / 改服务号菜单 / 改线上文案”类任务时：
|
||
|
||
1. 先读本文与 [生产发布规则](../PRODUCTION_RELEASE_RULES.md)
|
||
2. 在本地 `test-memind` 修改并 commit
|
||
3. 走文档规定的发布流程
|
||
4. 仅在发布后执行必要的 API 同步（如微信菜单）
|
||
5. **不得** SSH 到 105 直接改 `.mjs` / `.ts` / 前端资源
|
||
|
||
## 相关文档
|
||
|
||
- [生产 / 测试 / 预览隔离规程](service-isolation-runbook.md)
|
||
- [Portal 无源码迁移说明](no-source-portal-migration.md)
|
||
- [103/105 一次性升级实施记录](103-105-upgrade-runbook-2026-06-26.md)
|