外观
配置与素材要求
环境配置、广告运营规则和客户端标识属于不同层次。服务器环境变量控制服务运行;后台表单控制广告和奖励;APP 使用公开 App ID 与广告位编码发起请求。
服务环境变量
API 和 worker 应使用相同数据库、JWT 签名密钥和应用密钥加密配置。示例值是格式说明,不是可用于生产的共享凭据。
| 变量 | 用途 | 默认或约束 |
|---|---|---|
NODE_ENV | 运行环境 | production 启用安全 Cookie,并禁止本地 webhook 特例 |
PORT | API 监听端口 | 3000 |
BIND_HOST | API 监听地址 | 127.0.0.1;容器内使用 0.0.0.0 |
TRUST_PROXY | 可提供客户端 IP 的可信代理 | 默认 false;只接受明确 IP/CIDR 的逗号分隔白名单,禁止 true、跳数和全网范围 |
DATABASE_URL | MySQL 连接 | 必填;mysql://USER:PASSWORD@HOST:PORT/DATABASE |
JWT_SECRET | 客户端及管理员会话签名 | 至少 32 个字符;随机生成并保密 |
APP_ENCRYPTION_KEY | 服务端应用密钥的 AES-GCM 加密 | 32 随机字节的 64 位十六进制字符串 |
ADMIN_EMAIL | seed 创建的初始管理员邮箱 | seed 时必填;已存在则不重复创建 |
ADMIN_PASSWORD | seed 创建的初始管理员密码 | 非空;不会覆盖已有账号密码 |
ADMIN_NAME | 初始管理员名称 | Administrator |
PUBLIC_API_URL | 对客户端公开的 API origin | 生成素材链接使用;例如 https://ads.example.com,不带 /v1 |
CORS_ORIGINS | 允许跨域访问的网页 origin | 逗号分隔,必须包含真实协议和端口 |
ADMIN_ORIGINS | 管理后台写请求允许的 origin | 可单独设置;未设时使用 CORS 配置及默认逻辑 |
MEDIA_DIR | 本地素材保存目录 | 建议绝对路径;开发生成器指向 .runtime/uploads |
ALLOW_LOCAL_WEBHOOKS | 允许非生产环境回环回调 | 仅显式设 true 且非生产时生效 |
不要混淆 PUBLIC_API_URL 和客户端 baseUrl:
ts
// 服务端配置:PUBLIC_API_URL=https://ads.example.com
// 客户端配置需要 API 版本前缀:
const ads = new AdClient({ baseUrl: 'https://ads.example.com/v1' });1
2
3
2
3
.env 中包含 # 或空格的密码应加引号。启动脚本与 API 使用 dotenv 语义:
dotenv
# 以下仅展示语法,不是建议使用的真实凭据。
ADMIN_PASSWORD="replace # with your own value"1
2
2
数据库连接 URL 中的用户名、密码若包含 @、#、% 等保留字符,需要做 URL 编码。Compose 当前直接把 MYSQL_PASSWORD 拼入连接 URL,推荐使用初始化脚本生成的随机十六进制值,或显式改成编码后的完整连接 URL。
可信代理与限流
API 默认不信任 X-Forwarded-For,直接访问 API 的客户端不能通过伪造转发头改变限流身份。经过反向代理时,必须在 TRUST_PROXY 中仅填写由部署方控制的代理地址,例如:
dotenv
TRUST_PROXY=172.30.83.10/32,172.30.83.11/321
当前拒绝 true、数字跳数、loopback 等别名、主机名、0.0.0.0/0 和 ::/0。错误配置会阻止 API/Worker 启动。不要为了让限流“生效”而信任所有来源。
仓库 Nginx 在边缘入口使用 X-Forwarded-For: $remote_addr 覆盖外部请求提供的转发链,并清除 Forwarded,避免用户自己指定来源地址。Compose 的管理后台和播放器各有一个 Nginx 容器,API 仅信任这两个固定地址的 /32,不信任整个容器网络。
| Compose 配置 | 默认值 | 说明 |
|---|---|---|
DOCKER_NETWORK_SUBNET | 172.30.83.0/24 | 项目容器网络 |
DOCKER_DYNAMIC_IP_RANGE | 172.30.83.128/25 | 其他容器动态地址池,与网关固定地址分开 |
DOCKER_ADMIN_PROXY_IP | 172.30.83.10 | 管理后台 Nginx 固定地址 |
DOCKER_PLAYER_PROXY_IP | 172.30.83.11 | 播放器 Nginx 固定地址 |
如果与已有 Docker/VPN 网段冲突,四项一起调整,使动态池和两个固定地址属于同一子网且不重叠。Compose 自动将这两个地址写成 API 的 TRUST_PROXY 白名单;其他部署方式需要自行配置准确的网关地址。
如果 Nginx 前还有公网 HTTPS 负载均衡器,默认 $remote_addr 会是负载均衡器地址。应先在 Nginx 配置明确的受信任上游与 real-IP 处理,再覆盖传给 API 的转发头;不能直接接受公网任意 X-Forwarded-For,也不能把 API 的可信白名单改成全网。
当前限流仍是每个 API 进程内的计数,不是多副本共享限流:匿名 Token 每来源 IP 每 60 秒 60 次,其余 API 共用每 IP 每 60 秒 1200 次。管理登录另有 15 分钟窗口,同一 IP + 规范化邮箱最多 20 次失败/处理中检查,并保留每 IP 总共 200 次失败/处理中检查的上限。某一账户达到上限后,继续撞这个账户不会消耗其他账户的剩余 IP 登录额度;成功登录仅清理本账户失败记录,不抹掉该 IP 已有的其他失败。
多实例部署应在统一入口配置共享限流。NAT 下确实共用公网 IP 的用户仍可能共享 IP 总额度,这是 IP 限流本身的边界,应结合实际规模调整入口策略。
网页入口配置
| 配置 | 作用位置 | 说明 |
|---|---|---|
API_PROXY_TARGET | 后台和播放器的开发服务器 | 默认 http://127.0.0.1:3000;需要传入启动进程环境 |
VITE_PLAYER_URL | 管理后台构建 | 参考播放器入口,默认当前主机的 5174 端口 |
VITE_DOCS_URL | 管理后台构建 | 开发者文档入口,默认当前主机的 5175 端口 |
VITE_ 变量会进入前端构建,适合放公开地址,不能放应用服务端 key 或数据库凭据。构建变量修改后需要重新构建后台。仅把变量写进 API 的容器运行环境,不会修改已经构建的静态网页。
素材处理环境变量
| 变量 | 默认 | 生效规则 |
|---|---|---|
MAX_UPLOAD_BYTES | 50 MiB | 上传请求文件大小限制,范围被约束到 1–100 MiB |
MAX_VIDEO_SECONDS | 60 秒 | 视频检查允许的时长上限 |
FFPROBE_PATH | ffprobe | 实际内容、编码和时长检查 |
FFMPEG_PATH | ffmpeg | 视频封面生成 |
上传参数提高到 100 MiB 时,还要同步核对反向代理和入口网关的请求上限;仓库 Nginx 示例预留了 multipart 开销。
上传检查使用 FFMPEG_PATH/FFPROBE_PATH,但开发种子直接调用 PATH 中的 ffmpeg。
图片
- 支持静态 JPEG、PNG、WebP,以真实文件内容判断,不信任文件扩展名。
- 原始图片最多 20 MiB、4,000 万像素,不接受 SVG 或动画图。
- 处理时按方向信息旋转,最大尺寸收敛到 1920×1920 范围内,保持比例且不放大小图。
- 保存为 WebP。APP 使用响应的
kind、url、尺寸信息,不依赖原始上传文件名。
视频
- 当前支持 MP4 容器、H.264 视频;存在音频时要求 AAC。
- 校验像素格式、视频尺寸、有效时长及音轨;不把扩展名为
.mp4的任意文件当作有效视频。 - 生成 JPEG 封面,提供 Range 读取以支持正常视频播放。
- 当前不是通用转码服务。格式不符合时请在上传前转成兼容编码。
可在本地使用 FFmpeg 准备素材:
sh
ffmpeg -i input.mov -c:v libx264 -pix_fmt yuv420p \
-c:a aac -movflags +faststart output.mp41
2
2
首次上传后应在目标设备上验证画面、音频、首帧和完整播放;Web 参考播放器通过不等于已完成所有原生平台适配。
私有 S3 存储
设置 S3_BUCKET 后启用对象存储,否则使用本地目录。
| 变量 | 说明 |
|---|---|
S3_BUCKET | 私有存储桶名 |
S3_REGION | 默认 us-east-1 |
S3_ENDPOINT | S3 兼容服务地址;配置后启用 path-style |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | 可选显式凭据;未提供则使用环境身份链 |
读取素材时,API 可以返回 302 跳转到有效期 300 秒的签名地址。客户端应跟随正常 HTTP 跳转,不把临时地址当作永久资产地址。真实 S3、CORS 和 CDN 尚未在初版环境完成连接验证。
后台规则与生效范围
| 层级 | 可配置内容 | 对接影响 |
|---|---|---|
| 应用 | 状态、交付方式、每日合计次数、时区、回调地址 | 决定身份和奖励交付路线 |
| 广告位 | 业务编码、展示/激励、奖励类型与数量、每日次数、冷却、观看规则 | 客户端按 code 请求;不能在请求中任意指定奖励数量 |
| 投放 | 素材、排期、优先级、权重、展示配额、观看规则覆盖 | 同广告位不同素材可以采用不同观看规则 |
| 素材 | 图片或视频、内容、跳转链接、归档状态 | 投放前须完成检查并处于可用状态 |
图片 5 秒、视频完整播放、每用户每广告位每天 10 次、每用户每应用每天 30 次、冷却 60 秒,均是创建时的初始值。它们不是固定业务规则。
广告位还可配置 requireRewardIntent,默认 false。只有 rewarded 且应用采用 server_pull 或 server_webhook 时可开启;开启后创建会话必须携带匹配的一次性业务奖励意图。应用存在要求意图的广告位时,即使广告位暂停,也必须先关闭该要求才能切换为 client_claim。后台会明确拒绝不兼容的修改,应用与广告位同时编辑也受服务端事务约束。
应用和广告位每日奖励配额按应用时区分桶,仅用于 rewarded:创建会话时预留,达到 ELIGIBLE 后消费。普通 display 不占这两项奖励配额,但仍受广告位冷却限制。冷却从成功 start 起算。
投放的 dailyLimit 是该投放的展示配额,创建时预留、成功 start 时消费,不等同于单个用户的奖励次数。开始后提前关闭的未合格激励会话可能保留奖励配额至证据窗口清理;开始前关闭则释放预留。
已经创建的会话保存规则和奖励快照。UI 展示奖励应读取会话响应的 reward,不要只使用之前缓存的广告位配置。部分紧急停投检查会在 start 时重新执行;若返回 AD_UNAVAILABLE,不要继续显示该素材或自行判定获奖。
当前固定时效
以下时效是服务端代码中的当前策略,尚未做成后台可编辑规则:
| 对象 | 时效 |
|---|---|
| 客户端 token | 1 小时 |
| 奖励意图 | 创建后 1 小时 |
| 未开始会话 | 创建后 5 分钟内开始 |
| 展示窗口 | 开始后 10 分钟 |
| 证据窗口 | 开始后 20 分钟 |
| 首次领取或消费 | 达到奖励资格后 24 小时 |
20 分钟证据窗口不表示可以继续观看 20 分钟计入奖励;只计入发生在前 10 分钟展示窗口内且通过校验的证据。带 elapsedSeconds 的事件可在证据截止前补报,乱序事件按连续序号重放;旧客户端缺少该字段时按首次接收时间保守处理。上传检查使用 FFMPEG_PATH/FFPROBE_PATH,但开发种子直接调用 PATH 中的 ffmpeg。
以响应中的具体时间字段及服务端状态为准,客户端计时器不能替代服务端判定。已成功领取/消费的恢复行为参见 奖励与恢复。