docs: add 143 Memind-dev dual-machine development runbook

Document isolated dev ports, SSH tunnel, and Git sync workflow for Mac Studio. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-11 17:10:09 +08:00
parent 348e192800
commit 6e7a75a79e
1 changed files with 87 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 143 开发目录 Memind-dev
+
+> 在 Mac Studio（103，`john@180.159.29.143`）上与本地 Mac 并行开发 Memind 的约定。  
+> 生产运行目录仍是 `/Users/john/Project/Memind`；**日常改码只用** `/Users/john/Project-dev/Memind-dev`。
+
+## 目录对照
+
+| 机器 | 开发目录 | 生产 / 103 运行目录 |
+|------|----------|---------------------|
+| 本地 Mac | `/Users/john/Project/Memind` | — |
+| 143 | `/Users/john/Project-dev/Memind-dev` | `/Users/john/Project/Memind` |
+
+代码同步靠 Git 远端 `git@git.tkmind.cn:tkmind/memind.git`，不要用 rsync 拷源码。
+
+## 143 开发端口（与生产隔离）
+
+| 服务 | 生产 | Memind-dev |
+|------|------|------------|
+| Portal / API | 8081 | **8086** |
+| MindSpace H5 (Vite) | — | **5173** |
+| memind_adm | 8082 | **8087** |
+| Ops | — | **3003** |
+| Plaza | 3001 | **3004** |
+
+`.env` 在 Memind-dev 内单独维护（从生产 `.env` 复制后覆盖上表端口与 `MEMIND_RUNTIME_PROFILE=local`），**不要** commit。
+
+## 日常命令
+
+```bash
+ssh john@180.159.29.143
+cd /Users/john/Project-dev/Memind-dev
+source ~/.zshrc          # 加载 /opt/homebrew 的 node@22 / pnpm
+git fetch origin --prune
+git pull --ff-only
+pnpm install             # 仅 lockfile 变化时
+pnpm dev
+```
+
+本机浏览器经 SSH 隧道访问 143 上的 Vite：
+
+```bash
+ssh -L 5173:127.0.0.1:5173 -L 8086:127.0.0.1:8086 john@180.159.29.143
+# 然后打开 http://127.0.0.1:5173/?preview=mindspace
+```
+
+Cursor Remote SSH：打开文件夹 `/Users/john/Project-dev/Memind-dev`。
+
+## 双机同步流程
+
+**收工（任一台）：**
+
+```bash
+git status
+git add -A && git commit -m "..."
+git push origin feature/learn-assistant   # 或 main，需明确批准 push
+```
+
+**开工（另一台）：**
+
+```bash
+git fetch origin --prune
+git switch feature/learn-assistant
+git pull --ff-only
+```
+
+## Git SSH（143 必配）
+
+143 公钥需加入 `git.tkmind.cn`（端口 2222，见 `~/.ssh/config`）：
+
+```bash
+ssh john@180.159.29.143 'cat ~/.ssh/id_ed25519.pub'
+ssh -T git@git.tkmind.cn   # 在 143 上验证
+```
+
+未配公钥前，可临时用本机 `git bundle` 同步，但不建议长期使用。
+
+## 103 发布
+
+- 功能合并进 `main` 且 CI / verify 通过后，在 **生产目录** 拉最新 `main` 再跑发布脚本。
+- 禁止从 Memind-dev 脏工作区或功能分支直接 `release-portal-*-prod.sh`。
+- 发布前：`bash scripts/check-release-ready.sh`
+
+## 注意
+
+1. 两台机器不要长期各改同一分支却不 push/pull。
+2. Memind-dev 与生产共用 `DATABASE_URL` 时，开发操作可能影响线上数据，谨慎执行 destructive 脚本。
+3. `pnpm dev` 与 103 生产 Portal（8081）可同时存在；不要误改生产目录下的文件或重启生产 LaunchAgent。