yuxuanhui
124 lines
7.0 KiB
Markdown
124 lines
7.0 KiB
Markdown
# 市场数据同步 Job
|
|
|
|
`market-data-sync` 是外部调度器触发的一次性任务。FastAPI 进程不包含定时器；PostgreSQL 是策略查询事实源，`market-data` 卷中的 CSV 只作为 qfq 落地快照和恢复介质。
|
|
|
|
## 环境与数据库连接
|
|
|
|
开发环境由 `docker-compose.dev.yml` 启动项目自带的独立 PostgreSQL，容器内连接串保持：
|
|
|
|
```dotenv
|
|
ZHIXING_DATABASE_URL=postgresql://zhixing:zhixing@postgres:5432/zhixing
|
|
```
|
|
|
|
生产环境不启动项目自带 PostgreSQL。现有 1Panel PostgreSQL 容器通过外部 Docker 网络 `1panel-network` 的稳定别名 `postgresql` 访问，数据库和用户均使用 `zhixing-system`。生产 `.env` 必须显式设置连接串；Compose 不会回退到开发数据库：
|
|
|
|
```dotenv
|
|
ZHIXING_DATABASE_URL=postgresql://zhixing-system:<url-encoded-password>@postgresql:5432/zhixing-system?sslmode=disable
|
|
```
|
|
|
|
当前服务器执行 `SHOW ssl` 的结果为 `off`，因此使用 `sslmode=disable` 或省略该参数。若日后在 1Panel/PostgreSQL 中启用 TLS，再将它改成 `sslmode=require`。密码中的 `@`、`:`、`/` 等字符必须 URL 编码。启用 TLS 后的示例如下：
|
|
|
|
```dotenv
|
|
ZHIXING_DATABASE_URL=postgresql://zhixing-system:<url-encoded-password>@postgresql:5432/zhixing-system?sslmode=require
|
|
```
|
|
|
|
部署前确认外部网络和数据库容器都在该网络中：
|
|
|
|
```bash
|
|
docker network inspect 1panel-network --format '{{json .Containers}}'
|
|
docker inspect 1Panel-postgresql-5Fc7 --format '{{json .NetworkSettings.Networks}}'
|
|
```
|
|
|
|
迁移或同步容器连接成功后，可只输出当前连接是否使用 SSL（不会打印连接串）：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm --no-deps market-sync \
|
|
python -c 'import psycopg; from zhixing_server.bootstrap.config import get_settings; connection=psycopg.connect(get_settings().database_url); print(connection.execute("SELECT ssl FROM pg_stat_ssl WHERE pid=pg_backend_pid()").fetchone()[0]); connection.close()'
|
|
```
|
|
|
|
输出 `t` 表示当前连接使用 SSL，输出 `f` 表示未使用。本服务器当前应输出 `f`，与 `sslmode=disable` 配套；若日后要求 TLS，应先检查 PostgreSQL/1Panel 的 SSL 配置，再改用 `sslmode=require`。
|
|
|
|
运行时保留普通 `postgresql://` 形式供 Psycopg 3 使用；Alembic/SQLAlchemy 会自动转换为 `postgresql+psycopg://`，并保留 `sslmode` 等 query 参数。
|
|
|
|
## 首次部署
|
|
|
|
先准备 `.env`，至少设置 `ZHIXING_TUSHARE_TOKEN`、PostgreSQL 凭据和 `ZHIXING_DATABASE_URL`，然后执行迁移：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm migrate
|
|
```
|
|
|
|
首次初始化会回补六年交易日指标，并为当前沪深非 ST A 股获取六年 qfq 行情：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync --initialize
|
|
```
|
|
|
|
日常收盘后同步默认解析最近的开市日；也可以显式指定日期：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync --trade-date 2026-08-05
|
|
```
|
|
|
|
`success` 返回 0；覆盖率低于配置阈值或出现部分失败返回 2；没有可用成功结果或基础设施失败返回 1。CLI 输出不包含 Tushare token 或数据库密码。
|
|
|
|
行情阶段默认使用 8 路固定 worker；可通过 `ZHIXING_MARKET_DATA_MAX_WORKERS` 调低或调高，取值必须
|
|
至少为 1。每个 worker 从有上限的 PostgreSQL 连接池借用独立连接，主线程批量写入同步审计并通过
|
|
一次集合查询计算覆盖率。所有 worker 共用 Tushare 频控协调器；普通请求保持并发，命中 403、429 或
|
|
“访问频繁”等提示时共享 60/120/180 秒冷却窗口。若供应商频控持续发生，先把 worker 降到 1，再通过
|
|
`--retry-batch-id` 只恢复失败对象。
|
|
|
|
## Cron 与重试
|
|
|
|
宿主机 cron 只负责启动临时容器，不写入容器内部的 crontab。下面的示例每天工作日 18:00 触发；交易日历、唯一约束和 PostgreSQL advisory lock 使周末、节假日、重复触发和重叠触发保持安全：
|
|
|
|
```cron
|
|
0 18 * * 1-5 cd /srv/zhixing-system && docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync >> /var/log/zhixing-market-sync.log 2>&1
|
|
```
|
|
|
|
部分成功批次的输出会包含 `batch_id`。修复凭据、网络或数据库问题后，只重试该批次失败的股票和指标日期：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm market-sync \
|
|
--retry-batch-id <batch-id>
|
|
```
|
|
|
|
单只股票按数据库事务和 CSV 发布作为恢复边界。数据库提交失败时正式 CSV 不会替换；CSV 发布失败时数据库写入保持幂等，重试可以再次发布。成功批次完成后，数据库事实表和正式日期快照清理六年窗口起点以前的数据；失败对象保留上一次成功版本。
|
|
|
|
## 本地检查
|
|
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml config
|
|
docker compose -f docker-compose.dev.yml --profile jobs config
|
|
docker compose -f docker-compose.prod.yml config
|
|
docker compose -f docker-compose.prod.yml --profile jobs config
|
|
```
|
|
|
|
真实 PostgreSQL 迁移和批量 upsert 集成测试使用 `ZHIXING_TEST_DATABASE_URL` 显式开启；普通单元测试不会访问网络、Tushare 或数据库。
|
|
|
|
## 板块资金雷达 Job
|
|
|
|
`sector-radar-build` 同样是外部调度器触发的一次性任务，FastAPI 不会在进程内启动定时器。它只读取 Tushare 的 `trade_cal`、`dc_index`、`dc_member`、`stock_basic`、`suspend_d`、`daily` 和 `moneyflow_dc`，保存 point-in-time 原始快照与规范化事实，再生成明确标注为“知行独立实现”的版本化指标。生产运行时不请求 OneChartLab。
|
|
|
|
开发环境没有 token 时可以检查命令契约，但不能执行真实构建：
|
|
|
|
```bash
|
|
cd zhixing-server
|
|
uv run sector-radar-build --help
|
|
```
|
|
|
|
提供 `ZHIXING_TUSHARE_TOKEN` 并完成迁移后，可构建单日、按交易日顺序回填区间，或从一个 `partial`/`failed` publication 的来源检查点继续重试。失败 publication 会复用此前已成功保存的来源组；覆盖率不足的 partial 只刷新被标记为缺口的 `daily` 或 `moneyflow_dc`，不会全量重采：
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm sector-radar-build \
|
|
--trade-date 2026-08-28
|
|
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm sector-radar-build \
|
|
--start-date 2026-08-18 --end-date 2026-08-28
|
|
|
|
docker compose -f docker-compose.prod.yml --profile jobs run --rm sector-radar-build \
|
|
--retry-publication-id <publication-id>
|
|
```
|
|
|
|
重复输入通过内容 hash 复用已有成功发布，不产生无意义修订；同一目标日由 PostgreSQL advisory lock 阻止并发构建。`success` 或 `unchanged` 返回 0，覆盖率不足的 `partial` 返回 2，输入、上游、锁或基础设施失败返回 1。`partial`/`failed` 会保留审计，但读取端只选择 `success` 作为 last-good。当前版本只提供手工和外部调度入口，不新增生产 Cron；待真实账号 capability、到达时点和首轮回填验证完成后再单独启用调度。
|