mnote/infra/convex/README.md

# Convex 自托管（Windows 本机）

本目录用于在本机通过 Docker Compose 启动 Convex backend + dashboard，并使用 backend 自身的持久化卷存储（包含数据库与文件存储）。

在 local-first 方案下，这套 Convex 自托管环境定位为控制面、cloud source、compat 和可选 sync replica 运行底座；页面正文、默认附件和本地 AI 会话全文不再以它作为早期产品默认数据真相。

## 当前 functions 边界

- 仓库根 `convex/` 是当前 active Convex functions 部署源；目前只保留 `schema.ts` 与 `aiSessions.ts`，用于 ACP / Hermes runtime session store。
- `recycle/wolai-frontend/convex/` 是退役前端随带的历史实现，不允许作为当前部署 fallback。仍需要的 `documents` / `mediaAssets` / `users` / `workspaces` 等旧 functions，必须明确迁回 active 区或移动到外部辅助区；不再使用的应正式退役。
- `scripts/run-convex-deploy.js` 只从仓库根部署 `convex/`，缺少 active functions 时应失败，不应从 `recycle/` 回退。

## 启动

1. 确保仓库根目录 `.env.all` 存在（全局唯一 env 文件）。
2. 在本目录执行：

```bash
docker compose up -d
```

## 生成 Dashboard / CLI admin key

在本目录执行：

```bash
docker compose exec backend ./generate_admin_key.sh
```

## 访问地址（默认）

- Dashboard：`http://localhost:6791`
- Backend：`http://127.0.0.1:3210`
- HTTP Actions：`http://127.0.0.1:3211`
- 文件存储：由 Convex 管理（Dashboard 的 Files 页面可查看）

## 快速验证（可选）

### 1) 验证 Convex functions 可用

当前根 `convex/` 只保留 ACP / Hermes runtime session store，部署前可先确认 active functions 文件存在：

```bash
test -f convex/schema.ts && test -f convex/aiSessions.ts
```

### 2) 验证固定开发用户（阶段 3）

启动前端后访问：`http://127.0.0.1:3000/api/dev/whoami`

### 3) 验证异步任务骨架（阶段 5）

启动前端后：
- `POST http://127.0.0.1:3000/api/dev/jobs/demo`（body 可选：`{ "ms": 800 }`）创建 demo job
- `GET  http://127.0.0.1:3000/api/dev/jobs/demo?id=<jobId>` 查询状态（queued/running/succeeded/failed）