tkmind/memind
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

chore: add 105 runtime and openhands ops tooling

Browse Source
This commit is contained in:
john
2026-06-29 07:01:26 +08:00
parent 65e8a3a5a8
commit d7cbf3cc96
22 changed files with 1263 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/105-server-operations.md
+58
View File
@@ -56,6 +56,64 @@
**不要**使用已停用的 `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`）
菜单名称与链接定义在本地：
docs/local-dev.md
+22
View File
@@ -22,6 +22,28 @@ pnpm dev
pnpm open:local-test # 浏览器打开 H5
```
### LaunchAgent 常驻（推荐本机联调）
终端里跑 `pnpm dev` 会在 Cursor / 终端关闭时被 SIGTERM 停掉。若希望登录后自动拉起、掉线自恢复，可安装 LaunchAgent（与 imgproxy / goosed 同类）：
```bash
pnpm setup:dev-launchagent
# 卸载
pnpm setup:dev-launchagent:uninstall
```
| 项 | 值 |
|----|-----|
| Label | `cn.tkmind.memind-dev` |
| 进程 | portal (8081) + memind_adm (8082) + Ops (3002) + Vite (5173) |
| 日志 | `~/Library/Logs/memind-dev.log` |
安装后仍可用 `pnpm dev` 做前台调试；两者不要同时占用同一端口。重启服务：
```bash
launchctl kickstart -k gui/$(id -u)/cn.tkmind.memind-dev
```
需要旧式全栈联动时，改用：
```bash
docs/openhands-install.md
+85 -11
View File
@@ -1,18 +1,22 @@
# OpenHands 安装说明
> 目标：先把 OpenHands 独立安装并跑起来，确认可用后，再接入 `memindadm` 的 Goose 网关策略中心。
> 目标：先把 OpenHands 独立安装并跑起来，确认可用后，再接入 Goose / 路由策略。
>
> 原则：安装阶段不改动现有 Goose 服务，不影响当前生产/测试链路。
## 1. 推荐方案
如果你的目标是后续和 Goose 做集成，建议先用 **OpenHands CLI + GUI Server** 方式启动：
如果你的目标是后续和 Goose 做集成，要先分清两条链：
- 本地直接运行
- 可挂载当前仓库目录
- 便于后续做执行器接入验证
- `OpenHands Web / GUI`：浏览器访问的服务，适合人工打开页面验证
- `Goose -> OpenHands`：Goose 直接拉起 `OpenHands CLI` 进程做委托执行，不走 `127.0.0.1:3000` 这个网页入口
官方文档对 `openhands serve` 的说明是：它会通过 Docker 启动本地 GUI Server，支持挂载当前目录，适合直接对仓库做任务。
本仓库当前建议：
- 页面服务用 `Colima + docker compose`
- Goose 委托执行继续用本机 `OpenHands CLI`
这样边界最清楚，也不会把 Goose 和 OpenHands 强耦合到一个镜像里。
## 2. 前置条件
@@ -73,6 +77,44 @@ openhands serve --mount-cwd
如果你更偏向容器化，可按 OpenHands 的 Agent Canvas / Docker 文档走容器启动方式。这个方式适合未来把 OpenHands 作为更独立的执行环境来跑。
### 方式 D：本仓库 Colima compose
如果本机 Docker 实际跑在 Colima，而不是 Docker Desktop 默认 socket，可以直接使用仓库内置的 compose 文件：
```bash
cd /Users/john/Project/Memind
bash scripts/openhands-colima.sh pull
bash scripts/openhands-colima.sh build
bash scripts/openhands-colima.sh up
```
默认行为：
- 启动 `postgres:16-alpine`
- 启动本地 overlay 镜像 `memind/openhands-colima:local`
- 挂载 Colima socket：`/Users/john/.colima/default/docker.sock`
- 挂载当前仓库到容器内：`/workspace`
- 对外暴露 GUI 端口：`3000`
- OpenHands 持久化走本地 Postgres，而不是 SQLite
常用命令：
```bash
bash scripts/openhands-colima.sh build
bash scripts/openhands-colima.sh status
bash scripts/openhands-colima.sh logs
bash scripts/openhands-colima.sh restart
bash scripts/openhands-colima.sh down
```
当前 PG 默认值：
- `OPENHANDS_DB_NAME=openhands`
- `OPENHANDS_DB_USER=openhands`
- `OPENHANDS_DB_PASS=openhands_dev_password`
如果需要自定义，可在执行脚本前导出环境变量。
### 端口与资源
- GUI Server 默认会占用 `3000` 端口
@@ -133,11 +175,28 @@ openhands serve --mount-cwd
启动成功后，确认以下几点：
1. 浏览器能打开 OpenHands 的界面。
2. 可以创建一次简单任务。
3. 如果用了 `--mount-cwd`，任务可以看到当前仓库。
2. `curl http://127.0.0.1:3000` 返回 `200 OK`。
3. Postgres 中可以看到 OpenHands 表，例如 `event_callback`、`conversation_metadata`。
4. Docker 不报权限或 socket 错误。
## 7. 用于后续 Goose 集成时的建议
## 7. Goose 集成边界
当前 Goose 不是调用 `http://127.0.0.1:3000` 这个 GUI 服务，而是直接执行本机 `OpenHands CLI`：
- `GOOSE_OPENHANDS_BIN=/Users/john/.openhands/bin/studio-openhands`
- `GOOSE_OPENHANDS_RUNNER=host`
其中：
- `/Users/john/.openhands/bin/studio-openhands` 目前只是一个 wrapper
- 实际执行的是 `/Users/john/.local/bin/openhands`
这意味着：
- `Colima` 里的 OpenHands Web 服务，主要用于人手打开页面和验证 PG 持久化
- Goose 的 OpenHands 委托执行，主要取决于本机 CLI 是否可用、模型环境变量是否齐全
## 8. 用于后续 Goose 集成时的建议
为了后面接入 `memindadm`，建议你先准备好这些信息：
@@ -152,7 +211,7 @@ openhands serve --mount-cwd
如果你后面已经决定把 `Goose / Aider / OpenHands` 的模型统一收口到 `memindadm`，那么 OpenHands 这边也不要再单独维护自己的模型配置，统一从后台读取即可。
## 8. 和现有 Goose 服务的关系
## 9. 和现有 Goose 服务的关系
这一步是旁路安装，不会改动现有 Goose 服务。
@@ -163,7 +222,22 @@ openhands serve --mount-cwd
- OpenHands 先作为独立执行器接入
- 真正切流之前，先做只读审计和联调验证
## 9. 官方参考
## 10. 本地验证结论
本仓库本机 `Colima` 已验证通过：
- OpenHands Web 服务可访问
- OpenHands 数据落本地 Postgres
- 官方镜像直接切 PG 有迁移坑，因此当前 compose 使用的是仓库内的薄 overlay 镜像修复
相关文件：
- `/Users/john/Project/Memind/docker-compose.openhands-colima.yml`
- `/Users/john/Project/Memind/docker/openhands-colima/Dockerfile`
- `/Users/john/Project/Memind/docker/openhands-colima/002.py`
- `/Users/john/Project/Memind/docker/openhands-colima/010.py`
## 11. 官方参考
- OpenHands 安装文档
- OpenHands GUI Server
docs/release-deploy.md
+33
View File
@@ -12,6 +12,14 @@
4. 103 **禁止** `npm install`、`npm run build`、在线改源码后继续运行。
5. 切换后必须通过 Portal 健康检查；失败立即回滚。
补充：
- `103 / Studio` runtime 发布入口：`bash scripts/release-portal-runtime-prod.sh`
- `105` runtime 发布入口：`bash scripts/release-portal-runtime-105.sh`
- 两者都必须是 **runtime artifact**，不要直接发源码树
- `105` 与 `103` 的关键差异是：
`105` 为 Linux 环境，**不要携带本机 Mac 的 `node_modules`**；应在 `105` 切换前本机执行 `npm install --omit=dev --no-package-lock`
## 唯一入口
```bash
@@ -19,6 +27,13 @@ bash scripts/release-portal-runtime-prod.sh --dry-run
bash scripts/release-portal-runtime-prod.sh
```
如果目标环境是 `105`：
```bash
bash scripts/release-portal-runtime-105.sh --dry-run
bash scripts/release-portal-runtime-105.sh --yes
```
## 产物发布流程
1. 本地 commit 当前改动。
@@ -32,6 +47,24 @@ bash scripts/release-portal-runtime-prod.sh
9. 启动 Portal，检查 `127.0.0.1:8081/api/status` 为 200。
10. 旧源码 live 目录移入 `archives/`，线上不再保留可运行源码树。
## 105 runtime 发布差异
`105` 当前不是 launchd，而是 `systemd` 服务：
```text
goose-h5.service
WorkingDirectory=/root/tkmind_go/ui/h5
EnvironmentFile=/root/tkmind_go/ui/h5/.env
ExecStart=/opt/node/bin/node /root/tkmind_go/ui/h5/server.mjs
```
所以 `105` 发布时要额外满足：
1. 保留 `.env` / `MindSpace/` / `data/` / `users/` / `logs/` / `public/plaza-covers/`
2. 远端切换前在新的 runtime 目录执行 Linux 依赖安装
3. 最终用 `systemctl restart goose-h5` 拉起服务
4. 健康检查目标是 `http://127.0.0.1:8080/api/status`
## 禁止事项
- 禁止 `rsync_to_server.sh`