本地开发与验证

准备依赖、保护本地状态、启动 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 迁移循环不属于当前启动流程。