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

docs: clarify local and 103 runtime topology

Browse Source
This commit is contained in:
john
2026-07-03 16:34:02 +08:00
parent 996c83bbc8
commit ebf06b376b
13 changed files with 164 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mindspace-seamless-migration-runbook.md
+27 -24
View File
@@ -4,12 +4,14 @@
This runbook defines the no-loss migration path for extracting MindSpace from the Memind monolith.
Current execution scope:
Current production status:
- Phase A only
- local standalone service on the same machine
- no 103 usage
- no 105 rollout yet
- 103 already runs standalone MindSpace Service from `/Users/john/MindSpace`.
- The service is `cn.tkmind.mindspace-service` on `127.0.0.1:8082`.
- Portal live root remains `/Users/john/Project/Memind`.
- `/Users/john/Project/Memind/MindSpace` is legacy compatibility/storage context only, not the current MindSpace Service root.
Historical/local Phase A notes remain below for implementation context. For current 103 production truth, use [103 runtime topology](./103-runtime-topology.md).
## Invariants
@@ -24,7 +26,7 @@ Run MindSpace as a standalone local service while Memind uses `MINDSPACE_SERVER_
Phase A is complete when:
- standalone MindSpace service uses `/Users/john/Project/MindSpace/runtime` by default
- standalone MindSpace service uses `/Users/john/MindSpace` as the production service root on 103
- Memind can use `MINDSPACE_SERVER_ADAPTER=remote` against the standalone service
- `npm run verify:phase-a-local` passes for a real user with existing data
- Memind remote-mode HTTP page list, page create, and page delete pass through the standalone service
@@ -33,7 +35,8 @@ Phase A is complete when:
## Current data-root policy
- New default standalone data root: `/Users/john/Project/MindSpace/runtime`
- Production standalone service root on 103: `/Users/john/MindSpace`
- Old `/Users/john/Project/Memind/MindSpace` paths are migration source, rollback source, or legacy compatibility only
- Old Memind directories are treated as migration source and rollback source
- Data-root migration is executed by script, not by ad hoc manual copying
@@ -49,7 +52,7 @@ Phase A is complete when:
### Standalone MindSpace service
Path:
- `/Users/john/Project/MindSpace`
- `/Users/john/MindSpace` on 103 production
Responsibilities:
- bootstrap DB-backed local MindSpace services
@@ -62,7 +65,7 @@ Responsibilities:
### Standalone data-root overrides
Use these when you intentionally want a runtime root other than the default `/Users/john/Project/MindSpace/runtime`:
Use these when you intentionally want a runtime root other than the production default `/Users/john/MindSpace`:
- `MINDSPACE_SERVICE_H5_ROOT`
- `MINDSPACE_STORAGE_ROOT`
@@ -73,7 +76,7 @@ Use these when you intentionally want a runtime root other than the default `/Us
### 1. Start standalone MindSpace service
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
npm run migrate:data-root -- --yes
MINDSPACE_MEMIND_ROOT=../Memind \
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-token \
@@ -85,11 +88,11 @@ node server.mjs
### 1b. Start standalone service against a new data root
```bash
cd /Users/john/Project/MindSpace
MINDSPACE_MEMIND_ROOT=../Memind \
MINDSPACE_SERVICE_H5_ROOT=/Users/john/Project/MindSpace/runtime \
MINDSPACE_STORAGE_ROOT=/Users/john/Project/MindSpace/runtime/data/mindspace \
H5_USERS_ROOT=/Users/john/Project/MindSpace/runtime/users \
cd /Users/john/MindSpace
MINDSPACE_MEMIND_ROOT=/Users/john/Project/Memind \
MINDSPACE_SERVICE_H5_ROOT=/Users/john/MindSpace \
MINDSPACE_STORAGE_ROOT=/Users/john/MindSpace/data/mindspace \
H5_USERS_ROOT=/Users/john/MindSpace/users \
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-token \
MINDSPACE_SERVICE_PORT=19081 \
MINDSPACE_SERVICE_AGENT_WORKER_ENABLED=true \
@@ -113,7 +116,7 @@ Use the standard local startup flow already used in this repo.
### Phase A local gate
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-token \
@@ -141,7 +144,7 @@ Latest verified totals from the Phase A gate:
### Memind remote-mode HTTP gate
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
MEMIND_REMOTE_MODE_BASE_URL=http://127.0.0.1:18082 \
@@ -160,14 +163,14 @@ Expected result:
### Infra smoke
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
node scripts/loopback-smoke.mjs
```
### User-scoped smoke
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-token \
node scripts/loopback-smoke.mjs
@@ -181,7 +184,7 @@ Expected result:
### Local vs remote comparison
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
node scripts/compare-local-remote.mjs
@@ -197,7 +200,7 @@ Expected result:
### Write-path parity
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
node scripts/compare-write-local-remote.mjs
@@ -212,7 +215,7 @@ Expected result:
### Asset upload parity
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
node scripts/compare-asset-local-remote.mjs
@@ -227,7 +230,7 @@ Expected result:
### Conversation package parity
```bash
cd /Users/john/Project/MindSpace
cd /Users/john/MindSpace
MINDSPACE_LOOPBACK_USER_ID=<user-id> \
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:19081 \
node scripts/compare-conversation-package-local-remote.mjs
@@ -315,7 +318,7 @@ Rollback:
- stop standalone service
- point Memind back to `local` or stop the standalone service
- if needed, start standalone with `MINDSPACE_SERVICE_H5_ROOT=/Users/john/Project/Memind`
- if needed for rollback/compatibility, start standalone with an explicit legacy root; do not assume `/Users/john/Project/Memind/MindSpace` is the current production service root
- old Memind data root becomes active again immediately
## Deferred