From a20c9ed91fe5da5f2a1debd8ba94701d6013a2ce Mon Sep 17 00:00:00 2001 From: Marsway Date: Tue, 13 Jan 2026 16:01:05 +0800 Subject: [PATCH] update --- Log.md | 34 ------------------- docs/STRUCTURE.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 34 deletions(-) delete mode 100644 Log.md create mode 100644 docs/STRUCTURE.md diff --git a/Log.md b/Log.md deleted file mode 100644 index fc57c06..0000000 --- a/Log.md +++ /dev/null @@ -1,34 +0,0 @@ -# Job 执行全量日志（落盘） - -本项目在任务执行时，会将该次执行的 **全量日志** 落盘到 `data/logs`（容器内为 `/data/logs`）下，便于排障与留存。 - -## 1. 路径规则 - -- 根目录：`./data/logs/` -- 按任务分目录：`./data/logs//` -- 单次执行日志文件名： - - `YYYY-MM-DD_HH-mm-ss_log-.log` - - 时间戳使用 **Asia/Shanghai**（与调度时区一致） - -示例： - -```text -./data/logs/sync_oa_to_didi.sync_legal_entity/2026-01-13_10-20-33_log-1234.log -``` - -> 注意：若 `job_id` 中包含路径分隔符（`/` 或 `\`），会被替换为 `_`，避免产生目录穿越或多级目录。 - -## 2. 与 Admin 的 JobLog.run_log 的区别 - -- **`JobLog.run_log`（入库）** - - 展示在 Admin 的 JobLog 详情页 - - 有字节上限（会截断），适合快速浏览 -- **`data/logs/.../*.log`（落盘全量）** - - 尽力写入，不做长度截断 - - 适合完整排障、留存、归档 - -## 3. 运维建议 - -- 建议将 `./data/logs` 纳入备份或日志归档策略（按业务合规要求）。 -- 如需自动清理（防止无限增长），推荐在宿主机使用 `logrotate` 或定时任务做保留策略（本项目不内置自动清理逻辑）。 - diff --git a/docs/STRUCTURE.md b/docs/STRUCTURE.md new file mode 100644 index 0000000..7053a36 --- /dev/null +++ b/docs/STRUCTURE.md @@ -0,0 +1,83 @@ +```text +. +├── app/ # 核心框架层：加载/调度/执行/后台/安全/适配器 +│ ├── main.py # FastAPI 入口；挂载 SQLAdmin；启动时确保 key 与 DB schema +│ ├── admin/ # SQLAdmin 管理后台 +│ │ ├── views.py # Job/JobLog 的管理视图、校验、动作按钮、模板选择 +│ │ ├── routes.py # Admin 自定义 POST 路由（Retry/Run 等） +│ │ └── templates/ # 覆盖/扩展 SQLAdmin 的模板（list/details/edit 等） +│ ├── core/ # 运行时基础设施（配置/日志/上下文/捕获） +│ │ ├── config.py # Settings（从 .env 读取）；DB_URL/REDIS_URL/FERNET_KEY_PATH 等 +│ │ ├── logging.py # 全局日志配置（stdout + 可选文件） +│ │ ├── log_capture.py # “尽力捕获”本次执行日志到 JobLog.run_log（不影响执行） +│ │ └── log_context.py # 将 job_id/log_id 写入日志上下文（便于追踪） +│ ├── db/ # 数据层（SQLAlchemy） +│ │ ├── models.py # Job / JobLog 模型定义 +│ │ ├── engine.py # create_engine + SessionLocal +│ │ ├── crud.py # 基础 CRUD（读 Job、写 JobLog、清理日志等） +│ │ └── schema.py # 轻量 schema 自升级（create_all + 补列） +│ ├── security/ # 安全模块 +│ │ └── fernet.py # Fernet key 管理 + JSON 加解密（兼容脏数据） +│ ├── plugins/ # 插件加载 +│ │ └── manager.py # handler_path -> import -> BaseJob 子类校验 -> instantiate +│ ├── jobs/ # 插件规范 +│ │ └── base.py # BaseJob 抽象基类（run(params, secrets)） +│ ├── integrations/ # 适配器/SDK：业务 Job 禁止直接写 HTTP +│ │ ├── base.py # BaseClient（超时/重试/日志；统一 request/get_json/post_json） +│ │ ├── seeyon.py # SeeyonClient：致远 OA token 认证 + 自动携带 token header +│ │ └── didi.py # （若存在）滴滴侧 SDK/适配器封装 +│ └── tasks/ # Celery 任务引擎 +│ ├── celery_app.py # Celery 配置（broker/backend、timezone、beat_schedule 等） +│ ├── dispatcher.py # 定时调度：每分钟 tick，cron_expr 命中则触发 execute_job +│ └── execute.py # 统一执行入口：读库->解密->加载插件->run->写 JobLog +├── extensions/ # 业务插件层（必须独立于框架层） +│ ├── __init__.py +│ └── sync_oa_to_didi/ # 示例插件：仅演示 token 获取日志 +│ ├── __init__.py +│ └── job.py # SyncOAToDidiTokenJob（调用 SeeyonClient.authenticate 并记录日志） +├── docker/ # 镜像构建 +│ └── Dockerfile # Python 镜像 + APT 镜像源切换 + 安装依赖 +├── docker-compose.yml # 生产基线：backend/worker/beat/redis/postgres + ./data 挂载 +├── docker-compose.dev.yml # 开发叠加：源码挂载 + backend reload + worker/beat watchfiles 重启 +├── env.example # 环境变量示例（本地复制为 .env） +├── connecthub.sh # 一键脚本：build/start/restart/stop + dev-* + log +├── pyproject.toml # Python 依赖（FastAPI/Celery/SQLAdmin/psycopg/cryptography 等） +├── README.md # “开发手册”主文档（运行指南、Admin 使用、示例配置） +└── data/ # 运行数据目录（建议仅作为 volume，不作为源码管理） + ├── logs/ # 应用日志落点 + ├── pgdata/ # PostgreSQL 数据目录（volume） + └── connecthub.db # 旧 SQLite 残留（若已切换 PG，可视情况清理） +``` + +--- + +## 核心执行链路（从 Job 到 JobLog） + +1. **Job 定义**在 DB 表 `jobs`：`id/cron_expr/handler_path/public_cfg/secret_cfg` +2. **Beat** 每分钟触发一次 `dispatcher.tick`：读取 `jobs`，用 `cron_expr` 判断是否到点 +3. 到点后 `dispatcher` 调用 `execute_job.delay(job_id=...)` +4. **Worker** 执行 `execute_job`： + - 读 Job -> 解密 `secret_cfg`（Fernet，仅内存） + - PluginManager 动态加载 `handler_path` 指向的 `BaseJob` 子类 + - 调用 `job.run(params, secrets)` + - 捕获/汇总日志（run_log）与异常（traceback），写入 `job_logs`（Admin 可视化查看/重试） + +--- + +## 框架层 vs 插件层（边界提示） + +- **框架层（app/）**：只提供通用能力（调度、执行、加解密、日志、管理后台、适配器基类），不包含具体业务流程。 +- **插件层（extensions/）**：只放“具体业务 Job”，例如“同步员工/同步部门/同步 OA→滴滴”等，必须继承 `BaseJob`。 +- **外部系统调用**：禁止在 Job 内直接写 HTTP；必须通过 `app/integrations/*` 下的 Client。 + +--- + +## 运行数据与持久化（data/） + +`data/` 是运行时 volume： +- `data/pgdata/`：PostgreSQL 持久化数据 +- `data/logs/`：应用日志 +- `data/fernet.key`：Fernet key（正式环境必须固定，否则历史 secret_cfg 无法解密） + +建议：`data/` 仅作为挂载目录，不当作源码文件纳入版本管理。 +