memind/docs/103-105-upgrade-runbook-2026-06-26.md

# 103 / 105 一次性升级实施记录（2026-06-26）

> 历史记录说明：本文记录 2026-06-26 当时的一次性升级事实。2026-07-03 后，103 的 MindSpace Service 已独立部署到 `/Users/john/MindSpace`；`/Users/john/Project/Memind/MindSpace` 只作为旧链路兼容/存量目录处理。当前生产拓扑以 [103 runtime topology](./103-runtime-topology.md) 为准。

## 目标

本次升级的目标不是继续修补旧工作树，而是一次性把：

1. 本地三仓库收口为唯一源码真相。
2. `103` 收口为“只接收发布包”的正式运行机。
3. `105` 收口为入口 / 代理机，不再承担可写业务数据目录。  
   **后续禁止 SSH 直改 105 业务源码**；运维细则见 [105 服务器变更规范](105-server-operations.md)。

## 已确认的真实结构

### 103

- 主机：`john@58.38.22.103`
- 主运行根目录：`/Users/john/Project`
- 当前业务目录：
  - `/Users/john/Project/Memind`
  - `/Users/john/Project/memind_adm`
  - `/Users/john/Project/memind_plaza`
- 当前产物目录骨架已经存在：
  - `/Users/john/Project/backups`
  - `/Users/john/Project/incoming`
  - `/Users/john/Project/releases`

### 105

- 可达 SSH 入口：`root@120.26.184.105`
- 旧文档中的固定内网地址 `100.101.255.32` 当前已视为废弃，不应继续写入脚本或说明
- 当前 H5 运行目录：`/root/tkmind_go/ui/h5`
- 当前 Plaza 目录：`/root/tkmind_go/ui/plaza`
- 105 上没有 Goose 双实例，只是入口 / portal 层

## 关键结论

### 1. MindSpace 数据真身在 103，不在 105

103 `.env` 明确指向：

- `H5_USERS_ROOT=/Users/john/Project/Memind/users`
- `MINDSPACE_STORAGE_ROOT=/Users/john/Project/Memind/data/mindspace`
- `MEMIND_SHARED_PUBLISH_ROOT=/Users/john/Project/Memind/MindSpace`

因此：

- `103` 是 MindSpace 用户空间、发布页、资产存储的真实落盘位置
- 105 不是这批数据的主存储

### 2. 105 通过 rclone 挂载 103 的共享目录

105 现有 systemd mount：

- `memind-shared-mindspace.mount.service`
  - 把 `memind-mac:/Users/john/Project/Memind/MindSpace` 挂到 `/mnt/memind-shared/MindSpace`
- `memind-shared-storage.mount.service`
  - 把 `memind-mac:/Users/john/Project/Memind/data/mindspace` 挂到 `/mnt/memind-shared/data/mindspace`

这意味着：

- 105 的无缝升级前提是 **103 上这两条真实路径不能变**
- 可以重建代码目录
- 不能随意移动这两棵持久目录的位置

### 3. 本次升级不能把 MindSpace 数据从路径上“迁走”

如果本次升级把以下路径改掉：

- `/Users/john/Project/Memind/MindSpace`
- `/Users/john/Project/Memind/data/mindspace`
- `/Users/john/Project/Memind/users`

那么：

- 103 本地服务会断引用
- 105 的 rclone mount 会失效
- 旧发布页 / 用户空间会出现访问中断

因此本次升级的正确策略是：

1. 保持这三条路径不变
2. 让新 release 继续继承这些目录
3. 把“源码目录可手改”废除，而不是把“数据根路径”迁走

## 本次备份结果

### 103

备份目录：

- `/Users/john/Project/backups/upgrade-20260626-094108`

包含：

- `103-Memind-live.tgz`
- `103-Memind-persistent.tgz`
- `103-memind_adm-live.tgz`
- `103-memind_plaza-live.tgz`

其中最关键的是：

- `103-Memind-persistent.tgz`

它单独保存了：

- `MindSpace`
- `data`
- `users`
- `public/plaza-covers`
- `.env`

### 105

备份目录：

- `/root/service_backup/tkmind-upgrade-20260626-094109`

包含：

- `105-h5-live.tgz`
- `105-plaza-live.tgz`
- `105-h5.env`
- `105-service-config.tgz`

## 当前数据体量

### 103

- `/Users/john/Project/Memind/MindSpace`: `95M`
- `/Users/john/Project/Memind/data`: `40M`
- `/Users/john/Project/Memind/users`: `52K`
- `/Users/john/Project/memind_adm`: `112M`
- `/Users/john/Project/memind_plaza`: `617M`
- `/Users/john/Project/tkmind_go`: `45G`

### 重要说明

`/Users/john/Project/tkmind_go` 很大，但它不是本次无缝迁移的关键业务数据真身。

本次升级不应先去搬这 `45G`，而应优先保证：

1. `Memind` 的持久目录不丢
2. `105` 的入口配置不丢
3. 三个本地仓库的首次正式 bundle 发布可回退

## 推荐升级顺序

### 第一步：保留 103 持久路径不动

以下路径本次不改名、不挪位置：

- `/Users/john/Project/Memind/MindSpace`
- `/Users/john/Project/Memind/data/mindspace`
- `/Users/john/Project/Memind/users`
- `/Users/john/Project/Memind/public/plaza-covers`

### 第二步：三项目按发布包重建代码版本

建议顺序：

1. `Memind`
2. `memind_adm`
3. `memind_plaza`

原因：

1. `Memind` 决定主持久目录和 105 的共享挂载根
2. `memind_adm` 独立但依赖 `Memind` 共享实现
3. `memind_plaza` 最后切，避免前端入口先于主共享资源变化

### 第三步：105 只保留入口角色

本次升级后，105 应保留：

1. `goose-h5.service`
2. 反代 / 入口相关配置
3. 指向 103 的共享挂载与远端 API 目标

本次升级后，105 不应继续承担：

1. 可写业务数据真身
2. 源码发布主线
3. Goose 实例

## 这次如何做到“无缝”

无缝的关键不是不重启，而是：

1. 数据路径保持不变
2. 新版本继承同一批持久目录
3. 入口配置不突然指向新路径
4. 每次切换都有可回退包

因此本次切换原则是：

1. 先切代码
2. 不搬数据根
3. 不改共享路径
4. 切完再验证挂载和业务路径

## 切换后必须验证

### 103

1. `http://127.0.0.1:8081/api/status`
2. `http://127.0.0.1:3001/plaza`
3. MindSpace 已有用户空间可读
4. 发布页可打开
5. `data/mindspace/users/*` 能继续访问对应资产

### 105

1. `goose-h5.service` 正常
2. `/mnt/memind-shared/MindSpace` 挂载正常
3. `/mnt/memind-shared/data/mindspace` 挂载正常
4. H5 请求仍能正确回源 103 的 Goose / shared data