yuxuanhui
98 lines
5.2 KiB
Markdown
98 lines
5.2 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 或数据库。
|