本地开发与验证

准备开发依赖、保护本地状态、启动 Core-first 服务栈，以及区分质量检查和完整运行测试。

适用前提

这一页面向已经持有经维护者检查的源码副本的开发者。当前源码获取链接仍受限制，不要从旧数据库备份或历史环境文件恢复开发配置。下面所有命令都在源码根目录执行。

你需要 Node.js 20+、Corepack、锁定的 pnpm 9.7.0、Docker Engine 和 Compose 2.24.4+。Compose 开发覆盖文件使用 !override，更旧的版本不能保证正确解析。先用 node --version、corepack pnpm --version、docker info、docker compose version 确认环境。

准备与启动

./manage-services.sh setup
./manage-services.sh config
./manage-services.sh start
./manage-services.sh status

setup 会准备权限受限的 .state/core-dev.env 并安装冻结依赖；config 校验合并模型并列出服务名称。启动使用固定的 Compose project mywebdrive-core-dev，入口是 http://127.0.0.1:8080。同名项目可能和另一份开发副本冲突，不要同时启动多个副本来隔离测试。

开发栈包括数据库、Redis、对象存储、迁移、Core、Analytics Worker、邮件适配器、Storage API/Worker、Prometheus、Web 和 Nginx。只有入口和开发邮件端口向本机暴露。不能只启动前端就认为整个文件流程可用。

开发邮箱的特别限制

开发配置把邮件适配器替换成了 fake-email，监听本机 8025，它不会向真实邮箱投递。/v1/test/mailboxes/latest 需要配置 FAKE_EMAIL_TEST_TOKEN，并用收件人和 X-Test-Mailbox-Token 来读取。默认的开发 overlay 没有配置这个测试读取 token，打开 8025 也不是一个可以直接查看验证码的网页。

所以默认 start 成功并不意味着你就能完成登录闭环。需要登录测试时，可以使用仓库的隔离 smoke/浏览器测试配置，或者由维护者配置私有测试邮箱读取契约。不要公开 fake mailbox 或将测试 token 复用到生产环境，也不要从数据库推算验证码。

每日管理命令

命令	用途
`./manage-services.sh logs core-api`	查看指定有效服务最近 200 行日志
`./manage-services.sh logs`	查看整栈最近日志
`./manage-services.sh stop`	停止容器，保留卷和本地密钥
`./manage-services.sh config`	校验配置，不打印完整秘密配置
`./manage-services.sh reset --confirm`	删除本地容器和卷，保留状态文件；仅在数据可丢弃时执行

状态文件出问题时管理器会拒绝覆盖，你需要先核对文件类型、权限和保留需求。不要把 reset 当作普通重启来用。

运行验证

./manage-services.sh quality
./manage-services.sh smoke

quality 覆盖当前活跃工作区的构建、类型、lint、测试、生成物和文档合同，不启动容器。smoke 会构建隔离栈、使用临时卷并在完成后清理。pnpm run test:docs 和 pnpm run verify:docs 检查文档/OpenAPI 的一致性，但不能替代实际收信和文件往返测试。

浏览器 smoke 要检查登录、上传完成、下载内容、管理权限以及桌面/移动端状态。Linux 是上游视觉基线的权威，不要在 macOS 上重写 Linux 基线。旧的 legacy:help 和 legacy:status 仅用于观察；其他 legacy 命令退出码为 64。旧的 split-service 迁移循环不属于当前启动流程。