admin/getDomain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f4b4ed0afec280e4356ac7e313d8322a361a3301
getDomain/domain-api/deploy/multi-region
History
Your Name e9c0a75b8f debug
2026-04-17 01:04:11 +08:00
..
templates
debug
2026-04-16 23:00:25 +08:00
bootstrap_mainland.sh
first
2026-04-16 21:35:47 +08:00
bootstrap_overseas.sh
first
2026-04-16 21:35:47 +08:00
check_cluster.sh
first
2026-04-16 21:35:47 +08:00
check_mainland_controller.sh
first
2026-04-16 21:35:47 +08:00
install_mainland_controller_quick.conf.example
debug
2026-04-17 01:04:11 +08:00
install_mainland_controller_quick.sh
debug
2026-04-17 01:04:11 +08:00
install_mainland_worker_quick.conf.example
debug
2026-04-17 01:04:11 +08:00
install_mainland_worker_quick.sh
debug
2026-04-17 01:04:11 +08:00
install_overseas_quick.conf.example
debug
2026-04-16 22:29:58 +08:00
install_overseas_quick.sh
debug
2026-04-16 23:00:25 +08:00
prune_cluster_nodes.py
first
2026-04-16 21:35:47 +08:00
prune_cluster_nodes.sh
first
2026-04-16 21:35:47 +08:00
README.md
first
2026-04-16 21:35:47 +08:00
rehearse_multi_region.sh
first
2026-04-16 21:35:47 +08:00
simulate_cluster_node.py
first
2026-04-16 21:35:47 +08:00
simulate_multi_region.sh
first
2026-04-16 21:35:47 +08:00

README.md

domainCheck 跨地域部署入口

本文档对应当前推荐的最小可用部署形态：

  • 国外 1 台：domain-web + domain-api + postgresql_main
  • 大陆 1 台：redis + postgresql_runtime + scheduler + detect-worker

目标：

  • 后台和 API 放国外
  • 检测执行放大陆
  • 后续新增大陆 Worker 时，不再改整体部署方式

一、目录约定

统一使用：

/opt/domaincheck

仓库内部署入口：

  • deploy/multi-region/bootstrap_overseas.sh
  • deploy/multi-region/bootstrap_mainland.sh
  • deploy/multi-region/check_cluster.sh
  • deploy/multi-region/check_mainland_controller.sh
  • deploy/multi-region/simulate_cluster_node.py
  • deploy/multi-region/simulate_multi_region.sh
  • deploy/multi-region/prune_cluster_nodes.py
  • deploy/multi-region/prune_cluster_nodes.sh
  • deploy/multi-region/templates/*.env.example

二、国外机器部署

在国外机器执行：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/bootstrap_overseas.sh /opt/domaincheck

脚本会：

  • 创建运行目录
  • 检查 Python 虚拟环境
  • 安装 API 依赖
  • 安装 systemd 服务模板
  • 在 /etc/default/domaincheck-api 生成环境变量模板
  • 给出后续启动命令

三、大陆机器部署

在大陆机器执行：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/bootstrap_mainland.sh /opt/domaincheck controller

如果后面新增纯 Worker 节点：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/bootstrap_mainland.sh /opt/domaincheck worker

其中：

  • controller 表示这台机器承担 redis + runtime-db + scheduler + worker + sync-agent
  • worker 表示这台机器只承担 detect-worker

脚本还会在大陆机器生成：

  • /etc/default/domaincheck-worker

当前模板已内置同步相关占位配置：

  • SYNC_PUSH_ENABLED
  • SYNC_SOURCE_REGION
  • SYNC_TARGET_REGION
  • SYNC_TARGET_API_BASE_URL
  • SYNC_SHARED_TOKEN
  • SYNC_BATCH_SIZE
  • SYNC_POLL_INTERVAL_SECONDS

建议把每台大陆节点自己的身份信息放在这里，而不是直接修改 service 文件正文：

  • NODE_CODE
  • NODE_REGION=mainland
  • NODE_ROLE=control
    • 仅 controller 模板使用
  • NODE_ROLE=worker
    • 仅纯 Worker 模板使用
  • DB_*
  • REDIS_*

四、当前脚本定位

当前入口脚本是第一版“标准化部署脚手架”，优先解决：

  • 目录统一
  • systemd 模板统一
  • 节点环境变量入口统一
  • 新增节点时操作步骤统一

当前大陆 bootstrap 还会自动补齐一组最小 Python 依赖：

  • fastapi
  • uvicorn
  • pydantic-settings
  • psycopg2-binary
  • redis

这样 domaincheck-sync-agent 在大陆 controller 节点上可以直接启动，不会因为 app.sync_agent 缺少 API 侧依赖而失败。

当前脚手架还额外区分了“自动同步由谁跑”：

  • 海外控制面：
    • domain-api
    • 负责接收 runtime/sync-ingest
  • 内地 controller 节点：
    • domaincheck-sync-agent
    • 负责按轮询周期把本地最新投影推送到海外控制面

当前还不会自动安装数据库主从或自动创建跨地域同步链路。

原因：

  • 当前项目仍处于单 Worker 改造向多 Worker 任务模型过渡阶段
  • 真正的任务调度与跨地域结果同步需要后续代码配合落地
  • 但当前已经预留同步配置模板与同步记录查询接口，便于后续接入 sync-service
  • 当前控制面还会自动把运行态摘要写入 detect_sync_records
    • sync_type=runtime_projection
    • 仅在关键状态变化或达到最小采样间隔时写入
    • 作用是先把“同步观测面”跑起来，而不是替代最终的跨地域结果同步服务
  • 当 SYNC_PUSH_ENABLED=true 且配置了 SYNC_TARGET_API_BASE_URL 后：
    • 大陆 domaincheck-sync-agent 会按 SYNC_POLL_INTERVAL_SECONDS 自动尝试推送：
      • 最新一条 runtime_projection
      • 当前积压的 detect_result_projection 批次
    • 目标控制面通过 POST /api/v1/runtime/sync-ingest 接收
    • 若配置了 SYNC_SHARED_TOKEN，接收端会校验 X-Domaincheck-Sync-Token
    • GET /api/v1/runtime/sync-summary 还会返回：
      • detect_result_batches 用于直接观察最近检测任务的结果同步是否已接收、仍待推送或发生失败

五、当前已落地能力

截至 2026-04-16，当前代码已经具备：

  • 节点注册与心跳
  • 运行态表自动初始化
  • 集群节点状态接口
  • 检测任务主表与任务项表
  • 活跃任务摘要与任务详情接口
  • Worker 小批量领取、租约续租、重启释放和过期回收

可验证接口：

curl http://127.0.0.1:8100/api/v1/runtime/status
curl http://127.0.0.1:8100/api/v1/runtime/readiness
curl http://127.0.0.1:8100/api/v1/runtime/cluster
curl http://127.0.0.1:8100/api/v1/runtime/sync-summary
curl http://127.0.0.1:8100/api/v1/runtime/sync-records?limit=10
curl http://127.0.0.1:8100/api/v1/detect/job/active
curl http://127.0.0.1:8100/api/v1/detect/jobs

也可以直接执行一键联调：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/check_cluster.sh http://127.0.0.1:8100

这条命令当前除了原始接口输出，还会额外给出一段压缩摘要，直接汇总：

  • ready / attention / blocking
  • 在线控制面 / Worker 数
  • busy / stale / offline 节点
  • 同步投影 / 接收计数
  • 结果批次的：
    • synced
    • delivered
    • pushing
    • projected
  • failed
  • unsynced

如果要在大陆 controller 节点本机确认“这台机器本身是否已经具备 controller 身份”，还可以执行：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/check_mainland_controller.sh

这条命令会直接检查：

  • /etc/default/domaincheck-worker 是否存在
  • NODE_ROLE=control 是否正确
  • SYNC_PUSH_ENABLED / SYNC_TARGET_API_BASE_URL 是否已配置
  • domaincheck-worker
  • domaincheck-sync-agent 是否已启用并处于运行态

如果当前还无法真正部署到大陆机器，也可以先在国外测试机上做“单机模拟多节点联调”：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/simulate_multi_region.sh http://127.0.0.1:8100

这条命令会临时模拟：

  • mainland-controller-sim
  • mainland-worker-sim-01

用于提前验证：

  • runtime/readiness
  • runtime/cluster
  • 运行中心顶部的多机就绪度结论

结束时按 Ctrl+C，脚本会自动清理模拟节点记录。

如果测试服里已经残留了很久没心跳的旧节点记录，导致 runtime/readiness 一直被离线节点拖成 attention，可以先做清理：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/prune_cluster_nodes.sh --minutes 30 --dry-run
bash deploy/multi-region/prune_cluster_nodes.sh --minutes 30

如果只想清理某个确定已经废弃的节点：

bash deploy/multi-region/prune_cluster_nodes.sh --node-code mainland-worker-01

如果要判断大陆 Worker 是否已经真正接入，不要只看 systemctl，还要看：

  • /api/v1/runtime/cluster 中是否出现对应 node_code
  • last_heartbeat_at 是否持续刷新
  • role / region 是否符合预期
  • metadata.job_id / metadata.cycle_token 是否能在执行时出现
  • summary.online_worker_nodes 是否大于 0
  • summary.status_counts.busy 是否会在执行中增加

六、第二台大陆 Worker 接入建议

后续新增大陆 Worker 时，建议顺序为：

  1. 拉最新代码到新大陆机器
  2. 准备与主执行面一致的 Python 环境
  3. 配置该节点自己的：
    • NODE_CODE
    • NODE_REGION=mainland
    • NODE_ROLE=worker
  4. 执行：
cd /opt/domaincheck/domain-api
bash deploy/multi-region/bootstrap_mainland.sh /opt/domaincheck worker
  1. 启动后在国外控制面检查：
curl http://127.0.0.1:8100/api/v1/runtime/cluster

如果接口里出现新节点，并且心跳持续更新，说明节点接入成功。

如果是第二台及以上大陆 Worker，最少还要确认：

  • NODE_CODE 与其它节点不重复
  • 连接的是同一套大陆 Redis / runtime-db
  • /etc/default/domaincheck-worker 已按该机器单独填写
  • 若该机器不是 controller，则不要额外启 domaincheck-sync-agent

七、当前推荐联调命令

国外控制面建议至少保留下面这组命令：

curl http://127.0.0.1:8100/health
curl http://127.0.0.1:8100/api/v1/runtime/preflight
curl http://127.0.0.1:8100/api/v1/runtime/readiness
curl http://127.0.0.1:8100/api/v1/runtime/cluster
curl http://127.0.0.1:8100/api/v1/detect/status
curl http://127.0.0.1:8100/api/v1/detect/job/active
curl http://127.0.0.1:8100/api/v1/detect/jobs?limit=5

如需一次性确认控制面和执行面都接通，可以直接执行：

cd /opt/domaincheck/domain-api
bash deploy/multi-region/check_cluster.sh http://127.0.0.1:8100

观察重点：

  • 控制面节点心跳应持续刷新，而不是只在 API 启动时更新一次
  • 大陆 Worker 节点在运行检测时应显示 busy
  • detect/job/active 应能看到当前任务总量、完成量、节点分布和最近事件
  • detect/jobs 可用于回看最近几轮任务是否正常收敛
  • 当代理池暂时为空但允许直连时，检测控制页会显示 降级直连
  • 当代理池为空且不允许直连时，检测会话阶段会显示 等待代理
  • runtime/cluster.summary 中应能直接看出：
    • 当前在线控制面节点数
    • 当前在线 Worker 节点数
    • 当前 busy / stale / offline 节点清单
  • runtime/sync-summary 中可直接查看：
    • 是否启用同步推送
    • 当前配置的源地域 / 目标地域
    • 最近同步记录和状态分布
    • 若当前还未接入真正的 sync-service，也应至少能看到：
      • runtime_projection
      • detect_result_projection
    • 接入自动推送后，还应能看到：
      • runtime_push
      • runtime_ingest
      • detect_result_ingest

大陆 controller 节点建议额外确认：

systemctl status domaincheck-sync-agent --no-pager -l

如果同步配置已填写完整，则期望：

  • domaincheck-sync-agent 为 active (running)
  • 海外控制面的 runtime/sync-summary 中能同时看到：
    • runtime_projection
    • runtime_push
    • runtime_ingest

八、后续演进

后续会继续补：

  • 运行库初始化脚本
  • 节点配置模板
  • 结果同步服务
  • 多 Worker 调度服务模板

配套设计文档见：

  • docs/16_domainCheck_多机检测与跨地域部署设计.md
Reference in New Issue View Git Blame Copy Permalink