# 本地开发

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

## 第一次启动

```bash
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 <邮箱>` 提升为管理员。