外观
本地开发与文档部署
本页面向运行广告系统的开发者。只阅读文档不需要 MySQL、管理员账号或应用密钥;完整广告演示需要 API、数据库和素材文件。
环境准备
| 工具 | 用途 | 本项目基线 |
|---|---|---|
| Node.js | API、worker、构建工具 | 22,已有验证环境为 22.17.0 |
| pnpm | 安装和运行工作区 | packageManager 锁定 10.29.1 |
| MySQL | 配置、会话、奖励和通知记录 | 部署目标 8.4 LTS;本地初版验证使用 9.4.0 |
| FFmpeg / ffprobe | 视频检查、封面和演示视频生成 | 演示 seed 要求 ffmpeg 在 PATH;上传处理可另配二进制路径 |
在项目根目录执行安装,保持 pnpm-lock.yaml 与代码一起使用:
sh
pnpm install --frozen-lockfile1
如果之前用过自定义 pnpm store,继续使用相同 --store-dir,避免无必要地重建依赖目录。
只运行开发者文档
sh
pnpm dev:docs1
访问 http://127.0.0.1:5175。文档站是独立静态站点,启动时不读取应用服务端密钥,也不连接业务数据库。搜索使用浏览器内的本地索引。
启动全部本地服务
sh
pnpm dev1
此命令按顺序执行:
- 当根目录没有
.env时,生成随机开发凭据;已有文件保持原值。 - 校验管理员邮箱、密码和数据库 URL 是否非空。
- 在
.runtime/mysql-test启动独立 MySQL,或复用同工作区已运行的实例。 - 构建广告源契约包,生成 Prisma 客户端,执行版本化 SQL 迁移和种子初始化。
- 启动 API、通知 worker、管理后台、参考播放器及开发者文档。
| 服务 | 本地入口 | 是否需要登录 |
|---|---|---|
| 管理后台 | http://127.0.0.1:5173 | 管理员邮箱、密码 |
| Web 参考播放器 | http://127.0.0.1:5174/?appId=app_demo | 演示应用可匿名接入 |
| 开发者文档 | http://127.0.0.1:5175 | 不需要 |
| Swagger | http://127.0.0.1:3000/docs | 当前为接口目录 |
| API 健康检查 | http://127.0.0.1:3000/v1/health | 不需要 |
| 独立开发数据库 | 127.0.0.1:33307/ad_system | .env 中数据库配置 |
关闭终端前按 Ctrl+C。脚本会停止它创建的服务;复用的已有数据库进程不由该次命令关闭。端口已被其他进程占用时会报错,不会悄悄换到另一个端口。
管理员初始密码
读取本机 .env 中的 ADMIN_EMAIL 和 ADMIN_PASSWORD。密码只要求非空,没有最小或最大字符数。再次运行 seed 不会重置数据库中已有账号密码;修改 .env 不是密码重置操作。
第一次验证
sh
curl http://127.0.0.1:3000/v1/health1
预期响应:
json
{ "status": "ok", "version": "0.1.0", "database": "mysql" }1
开发种子会建立公开应用标识 app_demo,以及图片广告位 daily_bonus、视频广告位 daily_video。打开参考播放器,先完成一次真实观看与领奖,再接入自己的客户端。演示生成的是本地开发数据,不产生第三方广告收入。
如果同一安装身份多次测试触发频控,可在管理后台修改演示广告位规则。配置修改不会改变已经创建的会话;用新请求创建下一次会话后再观察。
使用已有数据库
pnpm dev 只管理本项目默认的独立开发数据库。使用自建或托管 MySQL 时,配置 .env 后分别执行:
sh
pnpm --filter @ad/provider-core build
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm dev:api1
2
3
4
5
2
3
4
5
分别在其他终端启动所需组件:
sh
pnpm worker
pnpm dev:admin
pnpm dev:player
pnpm dev:docs1
2
3
4
2
3
4
API 可以单独运行,但 server_webhook 奖励需要 worker 才会自动投递。MySQL 数据库结构由迁移文件维护,包含手写复合外键和严格 ID 比较规则,不用 prisma db push 替代现有迁移。
构建和托管文档
sh
pnpm docs:build
pnpm docs:preview1
2
2
构建产物在 apps/docs/.vitepress/dist,可以部署到静态文件服务器。内容包含参考代码下载,不包含本机 .env、数据库文件或管理员凭据。
当前构建默认挂载在站点根路径 /。若需要挂到 /developers/ 之类的子目录,先设置 .vitepress/config.mts 的 base 并重新构建;复制文件本身不会改变页面资源路径。使用 Nginx 时,需要让无扩展名路径优先匹配 $uri.html。
仓库提供 Dockerfile 的 docs 阶段及 Compose docs 服务,入口仍为本机 5175。容器配置尚未在此次环境运行实测;实际部署时应与 API、后台一起核对域名、网络和持久化配置。
查看源码
| 内容 | 仓库路径 |
|---|---|
| 文档 Markdown | apps/docs/guide、api、reference、examples、operations |
| 文档导航与主题 | apps/docs/.vitepress |
| HTTP 客户端 | packages/client-core/src/index.ts |
| Web 参考播放器 | apps/player-demo/src |
| API 路由 | apps/api/src/client.controller.ts |
| 奖励与会话策略 | apps/api/src/ads.service.ts |
| 业务后端示例 | examples/business-server/src/index.ts |
接下来阅读 快速开始,或直接进入 TypeScript 客户端参考。