Parcourir la source

docs(kb): §7.2.1 去掉 whoami 分流,日志统一 ${HOME}/log

tianyu.chu il y a 2 semaines
Parent
commit
2c68e8407b
4 fichiers modifiés avec 20 ajouts et 70 suppressions
  1. 4 2
      kb/00-项目架构.md
  2. 1 4
      kb/30-开发规范.md
  3. 12 62
      kb/90-重构路线.md
  4. 3 2
      kb/92-重构进度.md

+ 4 - 2
kb/00-项目架构.md

@@ -668,8 +668,10 @@ bin/datax-multiple-hive-job-starter.sh -gcd jobs/raw/trd -start-date 20260415 -e
 部署方式:git pull + rsync (publish.sh → re-all 分发)
 
 日志目录:
-  统一输出到 /opt/data/log/{module}/{dt}/{file}.log
-  (老项目按 whoami 分流到 /opt/data/log 或 ~/data/log,参见 90-重构路线.md)
+  统一输出到 ${LOG_ROOT_DIR}/{module}/{dt}/{file}.log
+  (LOG_ROOT_DIR 默认 ${HOME}/log,外配在 conf/env.sh;
+   release 用户 bigdata 落 /home/bigdata/log/...,个人落各自家目录。
+   老项目 whoami 分流 /opt/data/log 与 ~/data/log 已废弃,见 90-重构路线.md §7.2.1)
 ```
 
 ## 8. manual/ 目录执行规范

+ 1 - 4
kb/30-开发规范.md

@@ -135,7 +135,7 @@ flowchart TD
 - 禁用 `dict.__contains__(key)`,改用 `key in dict`
 - 禁止 SQL 字符串拼接(防 SQL 注入),使用参数化查询
 - 硬编码配置项必须外置到 `conf/`(见 `90-重构路线.md` §2)
-- 敏感信息(Webhook token、数据库账密)**不得入库**
+- 敏感信息(数据库账密)**不得入库**
 
 ### 4.2 SQL
 
@@ -180,9 +180,6 @@ flowchart TD
 4. **Hive/Spark SQL 字段常很长**:数仓里 `trd_order_pay_amt_rmb_total_1d` 这种 30+ 字符的字段名很常见,对齐后右边要留 40+ 空格,一屏横向放不下反而更难读
 5. **可读性不需要靠对齐**:每个字段一行 + 逗号前置已足够清晰
 
-#### 4.2.3 非 JetBrains 用户
-
-用 VSCode / Cursor / 纯 vim 的同学暂时手工遵守上述约定即可。后续若团队全面切换到非 JetBrains 工具链,会补一份 `.sqlfluff` 配置作为等价物,这份 xml 会随之归档或删除。
 
 ### 4.3 Shell
 

+ 12 - 62
kb/90-重构路线.md

@@ -44,7 +44,7 @@
 | 项目部署目录 `poyee-data-warehouse/` | `publish.sh` | 新项目发布目录为 `/home/bigdata/release/poyee-data-warehouse/` |
 | `DATAX_WORKERS=(m3 d1 d2 d3 d4)` + `DATAX_WORKERS_WEIGHTS` 权重 map | `init.sh:18-31`(含展开 `DATAX_WORKERS_QUEUE` 的循环) | workers 列表 + 权重 map **整体**移入 `conf/workers.conf`(ini 或 yaml 格式),`init.sh` 仅保留读取 + 展开逻辑 |
 | `HADOOP_CONF_DIR='/etc/hadoop/conf'` | `__init__.py` | 使用系统环境变量 |
-| `LOG_ROOT_DIR="/opt/data/log"` | `init.sh`、`__init__.py` | 移入 `conf/env.sh` |
+| `LOG_ROOT_DIR="/opt/data/log"` + whoami 分流 | `init.sh`、`__init__.py` | 删除 whoami 分支,单值改为 `${HOME}/log` 并迁入 `conf/env.sh`,见 §7.2.1 |
 | 钉钉 access_token | `dingtalk_notifier.py` | 移入 `conf/alerter.conf`(敏感项) |
 | 企微 Webhook Key | `dw_base/common/alerter_constants.py` | 外移到 `conf/alerter.ini`(**入库**——部署靠 git pull,gitignore 会拉不到;webhook key 不算高敏感,最多被拿去发垃圾消息),Python 侧改 ConfigParser 加载;`alerter_constants.py` 整个删除 |
 | DS API 地址 | `ds/config/base_config.yaml` | 已在 yaml,保持即可 |
@@ -149,58 +149,6 @@ default:
    - 瘦身后 `__init__.py` 只保留最基本路径定义,`PROJECT_ROOT_PATH` 仍可用,但拆分过程中要保证 `spark_sql.py` 加载 yaml 的那行代码拿到的根路径与瘦身前一致
    - **执行顺序建议**:先做 §三 `__init__.py` 瘦身,把 `PROJECT_ROOT_PATH` 的定义稳定下来;再做 §2.3 的 `spark-defaults.yaml` 接入。反过来做会踩到"瘦身后路径变了"的返工
 
-### 2.4 项目根 `.gitignore`
-
-**现状**:老项目根目录**没有** `.gitignore`,`.idea/workspace.xml`、`.claude/settings.local.json` 等个人状态文件随时可能被误提交,`conf/alerter.conf`(规划中的告警 Webhook,见 §2.2)也需要挡在版本控制外。
-
-**目标**:在项目根新建 `.gitignore`,在阶段 2 建立 `conf/` 目录的同一节奏下一起落地(顺序上先有 `.gitignore` 再把 `alerter.conf` 放进 `conf/`,避免敏感文件误入第一次提交)。
-
-**内容清单**:
-
-```gitignore
-# ---- Claude Code 本地设置 ----
-.claude/settings.local.json
-
-# ---- JetBrains 个人工作区 ----
-# 注意:.idea/ 不整体 ignore —— modules.xml / *.iml / inspectionProfiles/ 是
-# 团队可共享的项目结构配置,保留入库对新成员友好(开箱即用),这也是
-# JetBrains 官方推荐做法
-.idea/workspace.xml
-.idea/tasks.xml
-.idea/shelf/
-.idea/usage.statistics.xml
-.idea/dictionaries/
-.idea/httpRequests/
-
-# ---- Python / 构建产物 ----
-__pycache__/
-*.py[cod]
-*.egg-info/
-.pytest_cache/
-.venv/
-venv/
-
-# ---- 运行期产物 ----
-*.log
-dw_base.zip
-
-# ---- 开发者本地草稿区(datax-gc-generator 输出的参考模板等) ----
-workspace/
-
-# ---- 敏感配置(运行时自动从 datasource/ 注入或在 conf/ 本地覆盖) ----
-conf/alerter.conf
-```
-
-**注意事项**:
-
-1. **`.idea/` 不整体 ignore**:
-   - 入库:`modules.xml`、`*.iml`、`inspectionProfiles/`(项目结构 + 代码检查规则,团队共享)
-   - 忽略:`workspace.xml`、`tasks.xml`、`shelf/`、`usage.statistics.xml` 等个人/统计文件
-2. **`.claude/` 也不整体 ignore**:`settings.json`、`commands/`、`agents/` 是团队共享配置;只忽略 `settings.local.json`
-3. **`dw_base.zip`** 是 `spark_sql.py` 运行时生成的 PySpark 打包产物,属于构建产物不入库
-4. **`workspace/`** 是开发者本地草稿区(`datax-gc-generator` 输出的参考模板、临时 SQL 调试等),**永不入仓**;开发者认可的成品再手动复制到 `jobs/` 或 `manual/` 下提交
-5. **`conf/alerter.conf`** 一开始就放进 `.gitignore`:阶段 2 迁移钉钉/企微 Webhook 时,新建文件前 `.gitignore` 必须先就位
-
 **与仓库改名的联动**:
 
 仓库改名 `tendata-warehouse-release` → `poyee-data-warehouse` 时(阶段 1 尾声),`.idea/tendata-warehouse-release.iml` 也要改名为 `.idea/poyee-data-warehouse.iml`,并同步更新 `.idea/modules.xml` 里的引用。这一步不属于 `.gitignore` 的范畴,但和它是同一天会碰到的事,在阶段 1 的仓库改名 checklist 里一起记一笔。
@@ -264,7 +212,7 @@ resolve_env() {
 # env 判定优先级:命令行 -env > 本文件 DW_ENV
 # 默认锁定为 dev:本地调试开箱即用;DolphinScheduler / 生产脚本总是命令行显式 -env prod 覆盖
 DW_ENV=dev
-# LOG_ROOT_DIR=/opt/data/log
+LOG_ROOT_DIR="${HOME}/log"
 ```
 
 **`dw_base/datax/job_config_generator.py` 改造**:
@@ -623,12 +571,15 @@ else
 fi
 ```
 
-**方向(凭记忆:用户 2026-04-18 确认):分流策略保留,但目的地形态变更**
+**方向:删除 whoami 分流,统一落 `${HOME}/log/{module}/{dt}/{file}.log`**
+
+- release 用户 `bigdata`:`$HOME` = `/home/bigdata`,日志落 `/home/bigdata/log/{module}/{dt}/{file}.log`
+- 个人调试用户:`$HOME` = 各自家目录,日志落 `/home/{user}/log/{module}/{dt}/{file}.log`
+- `$HOME` 本身就按用户隔离,无需代码再判断 `whoami`
 
-- release 用户(`bigdata` / `dolphinscheduler`)的生产调度作业:日志落到 `/opt/data/log/{module}/{dt}/{file}.log`
-- 个人调试:落到 `~/log/{module}/{dt}/{file}.log`(不是原来的 `~/data/log`,去掉中间 `data/` 一级)
+**为什么去掉 `/opt/data/log` 这条路**:原来 release 用户走系统级 `/opt/data/log` 的理由是"生产日志不应混在个人 home",但 `bigdata` 本身就是专属调度账号,它的 `$HOME` 就是生产日志的合法归宿,不需要再多开一条系统目录。路径统一后,权限 / 轮转 / 清理策略只需按一套做。
 
-**为什么保留分流**:个人调试的日志本来就不该和生产日志混在同一系统目录(权限、轮转、审计、磁盘空间都不一样);而统一路径又会引入"调度用户没写权限"类新问题。保留分流是务实选择
+**为什么保留 `LOG_ROOT_DIR` 在 `conf/env.sh` 里**:虽然默认值只有 `${HOME}/log` 一条,但仍作为**单一默认值**外配到 `conf/env.sh`,保留后期改路径的口子(比如某天运维要求共享一块专用盘,改一处即可,无需改代码)
 
 **为什么改目的地形态为 `{module}/{dt}/{file}.log`**:
 - 当前老结构 `/opt/data/log/datax/20260418/xxx.log` 已按 `{module}/{dt}/` 分,但不是所有入口都遵守(spark、ds 等散落在各自子结构下)
@@ -636,10 +587,9 @@ fi
 - `{module}` 取值:`datax` / `spark` / `ds` / `csv` / `export` 等顶层入口名
 
 **代码改动:**
-1. 保留 `whoami == RELEASE_USER` 分支逻辑,但分支里走新模板路径
-2. `LOG_ROOT_DIR` 放到 `conf/env.sh`,两个分支里显式分别赋值为 `/opt/data/log` 和 `${HOME}/log`
-3. 日志文件路径拼接统一走一个工具函数 `log_path(module, dt, file)`(Python 和 Shell 各一份),避免入口脚本各自拼
-4. `RELEASE_USER` 作为单一来源定义在 `conf/env.sh`,与 publish.sh 共用
+1. 删除 `whoami == RELEASE_USER` 分支逻辑,`LOG_ROOT_DIR` 单值从 `conf/env.sh` 读,默认 `${HOME}/log`
+2. 日志文件路径拼接统一走一个工具函数 `log_path(module, dt, file)`(Python 和 Shell 各一份),避免入口脚本各自拼
+3. `RELEASE_USER` 作为单一来源定义在 `conf/env.sh`,与 publish.sh 共用(日志路径已不依赖它,但 publish.sh 仍要)
 
 ### 7.3 部署改进
 

+ 3 - 2
kb/92-重构进度.md

@@ -72,8 +72,8 @@
 - [ ] `RELEASE_USER="alvis"` → `RELEASE_USER="bigdata"` 并迁入 `conf/env.sh`
 - [ ] `RELEASE_ROOT_DIR="/home/alvis/release"` → `/home/bigdata/release` 并迁入 `conf/env.sh`
 - [ ] `DATAX_WORKERS=(m3 d1 d2 d3 d4)` + 权重 map 迁入 `conf/workers.conf`
-- [ ] `LOG_ROOT_DIR` 放入 `conf/env.sh`(release 分支 `/opt/data/log`、个人分支 `${HOME}/log`,见 `90-重构路线.md` §7.2.1)
-- [ ] **保留 `whoami` 分流**,但目的地改为 `{LOG_ROOT}/{module}/{dt}/{file}.log`(统一 3 层模板
+- [ ] 删除 `whoami == RELEASE_USER` 分流,`LOG_ROOT_DIR` 单值 `${HOME}/log` 放入 `conf/env.sh`(见 `90-重构路线.md` §7.2.1)
+- [ ] 日志路径统一模板 `${LOG_ROOT_DIR}/{module}/{dt}/{file}.log`(3 层
 - [ ] 实现 `log_path(module, dt, file)` 工具函数(Python / Shell 各一份,单一来源)
 - [ ] 钉钉 access_token 从代码移入 `conf/alerter.conf`
 - [ ] 企微 Webhook Key 从代码移入 `conf/alerter.conf`
@@ -152,3 +152,4 @@
 | 2026-04-18 | 修正早先文档误述:`dw_base/__init__.py:16` 实际上有 `os.environ['HADOOP_CONF_DIR'] = '/etc/hadoop/conf'`(原 2026-04-18 changelog 早条说"仓库内无 HADOOP_CONF_DIR export"不准确) | — |
 | 2026-04-18 | **§2.8 改造降级为"条件触发"**(第三轮修正):用户提供老项目真实生产 json 样例显示只写 `defaultFS`(无 `hadoopConfig`)也能跑 HA —— 说明老 worker 节点 `hdfs-site.xml` 配置完整,`hadoopConfig` 是**可选覆盖**而非 HA 必要条件。前两轮论断("必须加 `hadoopConfig`"、"运维把 xml 写死单 NN")都被推翻。§2.8 加"新环境 HDFS HA 自检清单"(`echo $HADOOP_CONF_DIR` / grep xml HA keys / `hadoop fs -ls hdfs://nameservice1/`),三项全过则整节改造不做;仅任何一项失败才启动 ini schema 升级 + `HDFSDataSource` 改造。92 阶段 2 checklist 相应改为"自检前置 + 条件触发"4 条子项 | — |
 | 2026-04-18 | **§2.8 锁定 Path B(第四轮,实测决定)**:新 CDH 环境三连实测(json 含/不含 `hadoopConfig` × `HADOOP_CONF_DIR` 设/不设),结论:对 DataX JVM,仅 json 的 `hadoopConfig` 块有效,`HADOOP_CONF_DIR` 无效(`datax.py` 不把 conf 目录入 classpath,与 `hadoop` 命令行不同)。老项目能纯 `defaultFS` 跑通最可能是老运维把 `hdfs-site.xml` 塞进了 DataX classpath 目录,新环境 `/opt/datax` 没这类预置文件。改造要点:(a) `HDFSDataSource.get_datasource_dict()` 吃 `[hadoop_config]` 整节注入 `hadoopConfig`;(b) 删除 `dw_base/__init__.py:16` `os.environ['HADOOP_CONF_DIR']` 死代码。简化 §2.8 文本:去掉 `ha_enabled` 开关(用 `[hadoop_config]` 节存在性代替)、去掉自检决策树(已决定)、去掉"运维手工改 IP"误记 | — |
+| 2026-04-20 | **§7.2.1 再次反转**:删除 `whoami == RELEASE_USER` 分流,`LOG_ROOT_DIR` 改为单值默认 `${HOME}/log` 并保留在 `conf/env.sh`(外配后期可改)。理由:`$HOME` 天然按用户隔离(bigdata/个人用户家目录不同),代码判断是多余一层;`bigdata` 本身就是专属调度账号,其 `$HOME` 即是生产日志合法归宿,不需要系统级 `/opt/data/log` 那条路。同步更新 `90-重构路线.md §7.2.1`(核心段)+ `§2.1 硬编码表行` + `§2.4 env.sh 草稿` + `00-项目架构.md §6 部署段` + `92 阶段 2 checklist` | — |