rakuten-api/.env.example

# 本仓库出三个服务，共用这一份配置：
#   抓取服务 python -m app.scraping.main —— 匿名、无状态、可多开实例
#   交易服务 python -m app.trading.main  —— 带账号登录态、有状态，只能单实例
#   下单任务网关 python -m app.gateway.main —— 任务队列 + 状态镜像，只能单实例
# 各自只读自己那部分，下面按用途分组标注。

# ---- 抓取服务监听地址，通常本地用 127.0.0.1，容器/服务器用 0.0.0.0 ----
RAKUTEN_APP_HOST=0.0.0.0
RAKUTEN_APP_PORT=31107

# ---- 交易服务监听地址（同机部署时端口必须与上面错开）----
RAKUTEN_TRADING_HOST=0.0.0.0
RAKUTEN_TRADING_PORT=31108

# ---- 下单任务网关监听地址（部署在服务器侧；本地 worker 出站长轮询取任务）----
RAKUTEN_GATEWAY_HOST=0.0.0.0
RAKUTEN_GATEWAY_PORT=31109

# 运行环境：dev / prod / test
RAKUTEN_APP_ENV=dev

# 日志级别：DEBUG / INFO / WARNING / ERROR
RAKUTEN_LOG_LEVEL=INFO
# 是否将日志写入文件（dev 默认 false，prod 默认 true；可显式覆盖）
RAKUTEN_LOG_TO_FILE=
# 日志目录（相对项目根目录）
RAKUTEN_LOG_DIR=logs
# 日志切割策略（Loguru 语法）：例如 100 MB / 1 day / 00:00
RAKUTEN_LOG_ROTATION=100 MB
# 日志清理策略（Loguru 语法）：例如 14 days / 30 days
RAKUTEN_LOG_RETENTION=14 days
# 日志压缩格式：zip / gz / tar.gz；留空表示不压缩
RAKUTEN_LOG_COMPRESSION=zip

# Bearer Token 鉴权密钥：请求需携带 Authorization: Bearer <token>
RAKUTEN_BEARER_TOKEN=REPLACE_WITH_TOKEN_32CHARS

# 单次抓取超时（秒）
RAKUTEN_REQUEST_TIMEOUT_SECONDS=30
# 对乐天站点的最大并发请求数
RAKUTEN_MAX_SITE_CONCURRENCY=8
# 单次抓取的最大尝试次数（含首次）：1 次直发，2 次换 cookie 重试，3 次起动用浏览器兜底
RAKUTEN_HTTP_MAX_ATTEMPTS=3
# Akamai cookie 最长复用时长（秒），超时后清空、由下一次请求的响应重新建立。
# cookie 是随目标页响应下发的，正常路径不会额外访问站点首页。
RAKUTEN_SESSION_TTL_SECONDS=1800

# 浏览器兜底：纯 HTTP 被反爬拦截时用 Playwright 取回 cookie 再回灌重试。
# 日常流量不会触发；未安装 playwright 时自动降级为不兜底（主链路不受影响）。
RAKUTEN_BROWSER_FALLBACK_ENABLED=true
# 浏览器无头模式（留空表示 dev 有头、其他环境无头）
RAKUTEN_BROWSER_HEADLESS=
# 使用的浏览器通道（Windows 可填 chrome；留空使用 bundled chromium）
RAKUTEN_BROWSER_CHANNEL=

# 代理地址（需要日本 IP 时配置，例如 http://127.0.0.1:7890）
# 建议两个服务各配各的：抓取被限速换 IP 即可，交易带账号，出口 IP 频繁漂移
# 反而会触发风控。
RAKUTEN_PROXY_SERVER=
# 代理用户名（如代理需要认证则填写）
RAKUTEN_PROXY_USERNAME=
# 代理密码（如代理需要认证则填写）
RAKUTEN_PROXY_PASSWORD=
# 不经代理的主机名（逗号分隔，支持 *.internal 这类通配符）。默认覆盖本机与 Docker
# 服务间通信；内部网关或抓取服务使用其它域名时，将其显式加入此列表。
RAKUTEN_PROXY_BYPASS=localhost,127.0.0.1,::1,rakuten-api,rakuten-trading,rakuten-gateway

# ---- OpenTelemetry traces（可选；默认关闭）----
# 启用后把抓取-解析链路以 span 导出到 OTLP/HTTP endpoint，
# 用于排查"抓到的内容为什么解析不出预期字段"。
# 解析失败时会把页面 HTML 作为 span event 上报（上限可配），便于事后复现。
RAKUTEN_OTEL_ENABLED=false
RAKUTEN_OTEL_ENDPOINT=https://oltp.jerryyan.top/v1/traces
# 服务名按服务覆盖；不设时两侧 main.py 分别按 rakuten-scraping / rakuten-trading 落地
RAKUTEN_OTEL_SERVICE_NAME=
# OTLP 鉴权头（形如 key=val,key=val）；当前 endpoint 裸跑，留空
RAKUTEN_OTEL_HEADERS=
# 失败 HTML 快照上限字节（默认 2MB，超出截断并标注 truncated=true）
RAKUTEN_OTEL_SNAPSHOT_MAX_BYTES=2000000
# 不上报 server span 的路径（逗号分隔正则，按 search 匹配完整 URL）。
# 默认排掉 /health：容器 HEALTHCHECK 每 30 秒探一次、上游也在轮询，
# 这些请求各自是一条孤立 trace，量大且没有信息量。留空表示不排除。
RAKUTEN_OTEL_EXCLUDED_URLS=/health$

# ---- 以下仅交易服务使用 ----
# 人工登录后落盘的 cookie 目录（相对项目根目录）。
# 里面是可直接冒充账号的凭据，已在 .gitignore 排除，不要提交、不要外传。
RAKUTEN_AUTH_STATE_DIR=.auth
# 下单金额上限（日元）：实际应付超过该值直接拒绝提交，防止解析出错或页面改版
# 导致买到远超预期的订单。设为 0 表示不设上限（不建议）。
RAKUTEN_ORDER_MAX_TOTAL_YEN=30000
# 付款后监控（订单列表页轮询）间隔（秒）与最大轮询次数。间隔不宜太短——同一账号
# 频繁访问订单页有被风控盯上的风险。默认 3 小时一次，最多 80 次（约 10 天）。
RAKUTEN_ORDER_MONITOR_POLL_INTERVAL_SECONDS=10800
RAKUTEN_ORDER_MONITOR_MAX_CHECKS=80

# 登录态失效时是否自动重登（需要项目根有 account.yaml，含明文密码）。
# 关闭时登录态一掉就抛 5001 / 转 needs_human，需要人工跑 scripts/login.py。
RAKUTEN_RELOGIN_ENABLED=true
# 自动登录（含撞验证码时等人工接管）的最长总耗时（秒）。无人值守的机器可以调小
# （如 60）以尽快失败转 needs_human。
RAKUTEN_RELOGIN_TIMEOUT_SECONDS=300
# 启动时是否自动登录一次：起服务即按 account.yaml 把登录态准备好，不必先在宿主机跑
# scripts/login.py。后台执行不阻塞端口，失败只记日志。
# **刻意留成注释**：裸机跑不开（代码默认 false，别在开发机上一启动就弹浏览器），
# 容器部署由 docker-compose.yml 给 true。这里一旦写成显式值，compose 里的
# `${RAKUTEN_AUTO_LOGIN_ON_START:-true}` 就会读到 .env 的值而失效——compose 的变量
# 插值和 env_file 读的是同一个 ./.env。要手动覆盖时才取消注释。
# RAKUTEN_AUTO_LOGIN_ON_START=false

# ---- 以下仅下单任务网关使用 ----
# 任务队列 SQLite 文件路径（相对项目根目录）。务必放在持久化卷上，丢了等于
# 丢了一批下单任务。查询通道（account_queries 表）在同一份库文件里。
# 详见 docs/order-gateway.md。
RAKUTEN_GATEWAY_DB_PATH=data/gateway.db
# 任务租约 TTL（秒）。worker 领取后必须在此时间内首次 report 或 renew，否则
# 任务被置为 stale（**绝不自动重投**，需要人工 reclaim）。
RAKUTEN_LEASE_TTL_SECONDS=300
# 长轮询单次最长挂起秒数。worker 端 wait 参数会被夹到这个上限。
RAKUTEN_LEASE_MAX_WAIT_SECONDS=60
# worker 心跳超时阈值（秒）。超过即视为失联，/health 报 degraded。
RAKUTEN_WORKER_OFFLINE_ALERT_SECONDS=300

# ---- 账号只读查询通道（网关与本地 worker 共享），详见 docs/order-gateway.md §11 ----
# 查询单租约 TTL（秒）。worker 领走后需在此期间回结果，否则自动重投回丢列。
# 与下单任务的关键区别：**只读操作可以安全重投**。
RAKUTEN_QUERY_LEASE_TTL_SECONDS=180
# 查询单整体存活上限（秒）。从创建算起，超过仍未完成即置 expired（多半本地 worker 不在线）。
RAKUTEN_QUERY_TTL_SECONDS=900
# 同一张查询单最多被领取几次。重投累计到此仍无结果即置 failed。
RAKUTEN_QUERY_MAX_ATTEMPTS=3
# 终态查询单保留时长（秒）。结果里带站点原始 JSON，超期由 sweep 清理。
RAKUTEN_QUERY_RETENTION_SECONDS=604800
# worker 侧单次站点读取上限（秒）。查询在等账号锁（下单正跑）时也会超时失败，
# 上游重发即可——只读，重发没有副作用。
RAKUTEN_ACCOUNT_QUERY_TIMEOUT_SECONDS=120
# order_list 查询缺省翻页上限。上游可用 params.max_pages 覆盖（1..20）。
RAKUTEN_ACCOUNT_QUERY_DEFAULT_MAX_PAGES=3
# 回报结果 JSON 体积上限（字节）。超限先丢站点原始 JSON，仍超限判失败让上游缩小窗口。
RAKUTEN_QUERY_RESULT_MAX_BYTES=1048576

# ---- 以下仅交易服务内的下单 worker 使用 ----
# 网关 URL。**留空则不启动 worker**，交易服务只跑登录态接口。
# 部署形态：本地机（NAT 后无公网入口）通过出站长轮询从这里领任务。
RAKUTEN_ORDER_GATEWAY_URL=
# worker 标识。同一时间只能有一个 worker 持有 lease，留空时取主机名。
RAKUTEN_WORKER_ID=
# 本地订单 SQLite 文件路径（执行事实的权威记录）。
RAKUTEN_TRADING_DB_PATH=data/trading.db
# 页面证据目录（HTML 快照 + 截图 + meta.json，按 task_id 分子目录）。
RAKUTEN_EVIDENCE_DIR=data/evidence
# 抓取服务基地址。worker 需要商品数据（加购用 purchase 块）时出站请求这里。
RAKUTEN_SCRAPER_BASE_URL=