john
229 lines
9.1 KiB
Markdown
229 lines
9.1 KiB
Markdown
# 本地开发
|
||
|
||
> 这是本机本地开发文档，只处理当前工作区里的源码联调，不做任何生产同步。
|
||
> `pnpm dev` 不再启动 Plaza；如果需要联动 Plaza，请显式运行 `pnpm dev:all`，或者单独运行 `pnpm dev:plaza` / `pnpm start:plaza`。
|
||
> Plaza 专用脚本的源码默认指向同级仓库 `../memind_plaza`；如你的目录不同，请用 `PLAZA_APP_DIR` 覆盖。
|
||
> 生产 / 测试 / 预览隔离仍单独看 [生产 / 测试 / 预览隔离规程](./service-isolation-runbook.md)。
|
||
|
||
`pnpm dev` 启动后，用 **127.0.0.1 + 端口** 访问本仓库自己的服务：
|
||
|
||
| 服务 | 地址 |
|
||
|------|------|
|
||
| MindSpace H5 | http://127.0.0.1:5173/?preview=mindspace |
|
||
| Ops 审核后台 | http://127.0.0.1:3002/ops/ |
|
||
| API / Portal | http://127.0.0.1:8081 |
|
||
| memind_adm | http://127.0.0.1:8082 |
|
||
| Plaza | http://127.0.0.1:3001/plaza |
|
||
|
||
```bash
|
||
pnpm install
|
||
cp .env.example .env
|
||
pnpm dev
|
||
pnpm open:local-test # 浏览器打开 H5
|
||
```
|
||
|
||
### H5 多个接口同时返回 500
|
||
|
||
如果 `5173` 页面里的 `/auth/status`、`/auth/wechat/config`、`/api/analytics/context`
|
||
同时返回 `text/plain` 500，先检查 Portal：
|
||
|
||
```bash
|
||
curl -i http://127.0.0.1:8081/auth/status
|
||
```
|
||
|
||
`8081` 无法连接表示 Vite 还在运行、但它代理的 Portal 已退出，并非这些路由同时故障。
|
||
前台 `pnpm dev` 会在任一受管子进程意外退出时结束整个开发栈；重新运行 `pnpm dev`
|
||
即可干净启动。LaunchAgent 模式则查看 `~/Library/Logs/memind-dev.log` 并按下节命令重启。
|
||
|
||
### 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
|
||
pnpm dev:all
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `H5_PORT` | 8081 | Portal / API |
|
||
| `VITE_PORT` | 5173 | MindSpace 前端 |
|
||
| `PLAZA_PORT` | 3001 | Plaza |
|
||
| `OPS_PORT` | 3002 | Ops SPA |
|
||
| `ADMIN_PORT` | 8082 | memind_adm |
|
||
| `H5_PUBLIC_BASE_URL` | http://127.0.0.1:5173 | 公开链接基址 |
|
||
| `PLAZA_APP_DIR` | ../memind_plaza | Plaza 专用脚本的源码路径（`pnpm dev:plaza` / `pnpm start:plaza` / `pnpm dev:all`） |
|
||
| `MEMIND_SESSION_BROKER_ENABLED` | `0`（未设置） | Session Broker 灰度开关；Patch 2+ 本地验证时可设 `1`，见 [H5 Session 架构](./h5-session-architecture-20260706.md) |
|
||
|
||
### MindSpace：本地 vs 生产（必须区分）
|
||
|
||
`pnpm dev` / `server.mjs` 启动时会读取 `MEMIND_RUNTIME_PROFILE`（见 `scripts/memind-runtime-profile.mjs`）：
|
||
|
||
| `MEMIND_RUNTIME_PROFILE` | 用途 | MindSpace 实现 |
|
||
|--------------------------|------|----------------|
|
||
| `local`（**默认**） | 本机日常开发 | Portal 内置 `MINDSPACE_SERVER_ADAPTER=local` |
|
||
| `split-service` | 本机验证 103 拆分架构 | `remote` → `http://127.0.0.1:8082` 独立 MindSpace 服务 |
|
||
| `production` | **仅 103 服务器** | 不覆盖 `.env`，以服务器配置为准 |
|
||
|
||
**本地 `.env` 推荐：**
|
||
|
||
```bash
|
||
MEMIND_RUNTIME_PROFILE=local
|
||
```
|
||
|
||
**本机要测 split-service 时：**
|
||
|
||
```bash
|
||
MEMIND_RUNTIME_PROFILE=split-service
|
||
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:8082
|
||
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-secret # 必须与 MindSpace LaunchAgent 一致
|
||
launchctl kickstart -k "gui/$(id -u)/cn.tkmind.mindspace-service"
|
||
pnpm dev
|
||
```
|
||
|
||
如需验证 Goose 的逻辑 workspace MCP，再让 Portal 与 MindSpace Service
|
||
使用相同的本地签名 secret；该值至少 16 个字符，只放本机 `.env`，
|
||
不得提交：
|
||
|
||
```bash
|
||
MINDSPACE_MCP_BASE_URL=http://127.0.0.1:8082
|
||
MINDSPACE_MCP_TOKEN_SECRET=replace-with-a-local-secret
|
||
# 可选；默认 12 MiB，必须大于等于 1024
|
||
MINDSPACE_MCP_MAX_BODY_BYTES=12582912
|
||
```
|
||
|
||
Portal 用 secret 签发绑定 user/session/package/workspace/tool allowlist
|
||
的短期 token，MindSpace Service 用同一 secret 验证；Goose extension
|
||
只收到 scoped token，不会收到签名 secret。该 MCP 配置目前用于
|
||
`split-service` 联调。配置完整时 DOCX 目标写入和长图渲染也会经过
|
||
MindSpace Service；未配置时不会开放 `publish_page`，其它工具保留
|
||
本地兼容行为。
|
||
|
||
验证当前源码的本地 split-service 链路可运行：
|
||
|
||
```bash
|
||
npm run smoke:mindspace-split-service
|
||
```
|
||
|
||
该 smoke 会构建本地 `.runtime/mindspace-service`、启动临时独立
|
||
MindSpace RPC 服务，并通过 remote adapter 验证 health/contract、
|
||
workspace 写读、微信 HTML 交付与 fresh thumbnail；不会发布或上传
|
||
runtime artifact。它会读取本机配置的开发数据库并创建唯一的
|
||
`split-service-smoke-*` session/package 记录，退出时会清理对应
|
||
package/artifact，并把临时文件根删除。
|
||
|
||
remote adapter 会在 Portal 启动时校验 `/mindspace/v1/contract` 的
|
||
`contractVersion`、required capabilities 与关键 binding。如果本机
|
||
`8082` 仍是旧 MindSpace runtime，Portal 会 fail-fast，而不是等到
|
||
页面交付时才出现 `Unknown binding`。
|
||
|
||
排查 package / artifact / public URL 链路：
|
||
|
||
```bash
|
||
npm run audit:conversation-packages -- --limit 100
|
||
npm run trace:mindspace-artifact -- --public-url http://127.0.0.1:5173/MindSpace/<owner>/public/page.html
|
||
```
|
||
|
||
启动后 Portal 日志应出现：`[Portal] Runtime profile: MEMIND_RUNTIME_PROFILE=local, MINDSPACE_SERVER_ADAPTER=local, ...`
|
||
|
||
**禁止：** 把 103 生产 `.env`、RDS 连接串、`MINDSPACE_REMOTE_AUTH_TOKEN` 生产值复制进本机 Git 仓库。
|
||
|
||
### H5 Session 架构本地全量联调（`0706-bug干净` 分支）
|
||
|
||
在 **本机 `.env`**（勿提交 Git）打开下列开关后重启 `pnpm dev`：
|
||
|
||
```bash
|
||
MEMIND_SESSION_BROKER_ENABLED=1
|
||
MEMIND_ROUTER_NORMALIZED_DECISION=1
|
||
MEMIND_SSE_EVENT_TAXONOMY=1
|
||
MEMIND_RUN_STREAM_REPLAY=1
|
||
MEMIND_H5_HTML_FINISH_GUARD=1
|
||
```
|
||
|
||
| 开关 | 验证点 |
|
||
|------|--------|
|
||
| `MEMIND_SESSION_BROKER_ENABLED` | Portal 启动日志、`sessionAccess` 路径 |
|
||
| `MEMIND_SESSION_BROKER_METRICS` | `[session_broker.*]` structured log（§13.4） |
|
||
| `MEMIND_ROUTER_NORMALIZED_DECISION` | gateway 读 `decision.route` / `session_hint`；`shadow` 仅打 `[router-shadow]` 日志 |
|
||
| `MEMIND_SSE_EVENT_TAXONOMY` | SSE payload 多 `taxonomy` 字段 |
|
||
| `MEMIND_RUN_STREAM_REPLAY` | run SSE 含 `id:`，断线重连补发 |
|
||
| `MEMIND_SESSION_STREAM_REPLAY` | session SSE 持久化 + Last-Event-ID 重连补发（4c） |
|
||
| `MEMIND_H5_HTML_FINISH_GUARD` | Finish 后假交付检测 / 自动 repair |
|
||
|
||
启动后应看到类似：
|
||
|
||
```text
|
||
[Portal] H5 session flags: MEMIND_SESSION_BROKER_ENABLED, ...
|
||
```
|
||
|
||
回归：
|
||
|
||
```bash
|
||
npm run verify:h5-session-patches
|
||
# 内含：单测、§5.7 session broker coverage、goosed proxy boundary、MindSpace publish guards
|
||
```
|
||
|
||
手工 soak 清单（全量开发完成后执行）：[pending-fixes/h5-local-soak-20260706.md](./pending-fixes/h5-local-soak-20260706.md)
|
||
|
||
关闭某项：对应变量改 `0` 或删除后重启 dev。
|
||
|
||
Plaza 本地开发说明见 [plaza-local.md](./plaza-local.md)。生产发布、同步与回滚不要在这里处理，统一看 [生产更新发布指南](./release-deploy.md)。
|
||
|
||
### 本地 `.env` 与 103 生产 `.env` 分离
|
||
|
||
| 项 | 本地（本机 `.env` / `../../.env.local`） | 103 生产（服务器 `/Users/john/Project/Memind/.env`） |
|
||
|---|---|---|
|
||
| 配置真相 | 复制 `.env.example`，只填本地联调值 | 仅在 103 维护，**不提交 Git** |
|
||
| `TKMIND_API_TARGET` | 通常单实例 `https://127.0.0.1:18006` | 9 个 goosed target（`18006`–`18014`），见 [103 runtime topology](./103-runtime-topology.md) |
|
||
| `H5_PUBLIC_BASE_URL` | `http://127.0.0.1:5173` | `https://m.tkmind.cn` |
|
||
| `MEMIND_SESSION_BROKER_ENABLED` | Patch 2 起可本地设 `1` 验证 | 灰度窗口由运维在 103 `.env` 单独开启 |
|
||
| RDS / Redis | 可连本地 MySQL 或留空 | 生产 RDS + Redis，见 103 `.env` |
|
||
|
||
硬规则：不要把 103 的 `.env`、密钥、RDS 连接串复制进仓库；`.env.example` 只记录变量名与本地示例值。
|
||
|
||
## 公众号 Agent 调试
|
||
|
||
服务号消息转发到专属 Agent 这条链路默认关闭，只有显式设置下面这些变量后才会启用：
|
||
|
||
- `H5_WECHAT_MP_ENABLED=1`
|
||
- `H5_WECHAT_MP_APP_ID`
|
||
- `H5_WECHAT_MP_APP_SECRET`
|
||
- `H5_WECHAT_MP_TOKEN`
|
||
|
||
服务号后台需要把服务器地址指向：
|
||
|
||
```text
|
||
{H5_PUBLIC_BASE_URL}/webhooks/wechat-mp/messages
|
||
```
|
||
|
||
当前版本只支持“明文模式”回调，不支持 `aes` 安全模式解密。要保证 H5 微信 OAuth 和公众号消息使用同一个服务号 `AppID`，这样消息里的 `openid` 才能直接命中已绑定用户。
|
||
|
||
如果要立即停用这版，不改代码也可以先把：
|
||
|
||
```bash
|
||
H5_WECHAT_MP_ENABLED=0
|
||
```
|
||
|
||
然后重启 `server.mjs`。这相当于运行时止血；如果确认整版不要，再按代码回撤处理。
|