memind/docs/105-server-operations.md

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