本地开发

进程	地址
voko-server（API）	http://localhost:9201，健康检查 /healthz
voko-worker	无端口，日志里每分钟一次心跳
voko-web（员工端 + /admin）	http://localhost:5201，`/api` 代理到 9201

第一次启动

nvm use && corepack enable && pnpm install
cp apps/voko-server/.env.example apps/voko-server/.env   # 已有 .env 则跳过
pnpm mysql:up                                            # 本地 MySQL，确保 voko 库存在
pnpm --filter @voko/server db:init                       # 只对空库
pnpm dev:user admin@example.test admin123                # 本地管理员（只用于本地库）
pnpm --filter @voko/server dev
pnpm --filter @voko/web dev
pnpm --filter @voko/server worker                        # 需要时

本地 MySQL 可以与 shadiao-2d 共用同一个 Docker MySQL 服务（pnpm mysql:up 发现端口已开且口令可用时只确保 voko 库存在，不再起新容器）。

配置来源

apps/voko-server/.env 的 SMTP（service@voko.world）与大模型配置沿用 shadiao-2d visual-game-server 的同名变量；AUTH_TOKEN_SECRET 为 VOKO 单独生成，不与 Visual Game 共用；DATABASE_URL 留空即连本地 voko。

本地管理员

pnpm dev:user <邮箱> <密码> [显示名] [admin|operator|user] 对同邮箱 upsert，并重置密码与角色。只能用于本地开发库，禁止用于共享库。已在网页注册的账号可用 pnpm --filter @voko/server admin:grant <邮箱> 提升为管理员。