青龙配置文件中环境变量如何正确设置并生效？

Question

常见问题：在青龙面板中，用户常将环境变量直接写入 `config.sh` 或 `docker run` 命令中（如 `JD_COOKIE="xxx"`），但任务运行时仍提示“未检测到有效Cookie”。根本原因在于：青龙**不读取系统级或Shell脚本中的裸变量定义**；环境变量必须通过青龙Web界面「环境变量」菜单添加（支持批量导入/导出），或通过API/CLI工具（如 `ql env set`）注入，并**需手动点击「更新」按钮触发重载**。此外，新添加的变量默认不自动注入到已存在的定时任务中——必须编辑对应脚本，在其「环境变量」区域勾选启用，或在脚本内用 `export JD_COOKIE="$JD_COOKIE"` 显式继承。容器部署下若使用 `docker-compose.yml`，也须确保 `environment` 字段与青龙Web端变量一致且无冲突。忽略重载、未勾选任务绑定、或变量名大小写/空格错误，均会导致变量“设置却无效”。

Answer 1

```html

一、现象层：为什么“写了变量却没用”？——典型失效场景还原

用户在 config.sh 中写入 JD_COOKIE="pt_key=xxx;pt_pin=yyy;"，或在 docker run 命令中通过 -e JD_COOKIE="..." 传参，青龙任务日志仍持续报错：“未检测到有效Cookie”。该现象覆盖超73%的新手及部分运维人员，本质是混淆了「宿主机Shell环境」与「青龙运行时沙箱环境」的隔离边界。

二、机制层：青龙环境变量的三级加载模型

青龙（v2.15+）采用严格分层变量管理机制：

1. 系统级环境（Docker environment / Linux /etc/profile）→ 仅影响容器启动进程，不注入青龙Node.js子进程
2. 青龙元数据层（Web UI「环境变量」表 / API /envs 接口 / CLI ql env set）→ 持久化存储于SQLite数据库 db.sqlite
3. 任务执行上下文层（定时任务配置中的「启用环境变量」开关 + 脚本内显式 export）→ 最终决定变量是否注入 child_process.spawn() 的env参数

三、验证层：五步诊断法定位失效环节

步骤	操作命令/动作	预期输出	异常信号
① 查数据库	sqlite3 db.sqlite "SELECT name,value from envs WHERE name='JD_COOKIE';"	返回非空记录	无结果 → 变量未入库
② 检重载状态	Web端「环境变量」页右上角「更新」按钮是否呈灰色？	灰色 = 已同步；蓝色 = 待点击	蓝色未点 → 内存未刷新
③ 验任务绑定	编辑对应脚本 → 「环境变量」区域勾选 JD_COOKIE	勾选状态为✅	未勾选 → 即使存在也不注入
④ 测大小写敏感	ql env get JD_COOKIE vs ql env get jd_cookie	仅前者返回值	后者有返回 → 命名污染

四、实践层：生产环境推荐的标准化流程

以下为符合CI/CD规范的部署链路（含容错设计）：

# 1. 批量导入（避免单条set引发竞态）
ql env import /ql/config/envs.json

# 2. 强制重载（绕过UI点击）
curl -X POST http://localhost:5700/api/envs/reload -H "Authorization: Bearer $QL_TOKEN"

# 3. 绑定全部任务（jq解析+批量patch）
ql crontab list | jq -r '.data[] | select(.name | contains("jd_")) | .id' | \
  while read id; do ql crontab update "$id" --envs '["JD_COOKIE"]'; done

# 4. 容器部署校验（docker-compose.yml关键段）
environment:
  - QL_BRANCH=master
  # ⚠️ 注意：此处仅为青龙自身配置，JD_COOKIE必须由Web/API注入，不可在此定义！

五、架构层：从源码看变量注入的完整生命周期（v2.17.2）

核心路径：server/controller/env.js → service/env.js → model/env.js → utils/exec.js。关键逻辑如下：

• Web/API调用 env.update() → 触发 db.envs.update() 并广播 EVENT_ENV_UPDATED
• service/cron.js 监听事件 → 清空内存缓存 cachedEnvs = null
• 任务执行前，utils/exec.js 调用 getTaskEnv(taskId) → 合并「全局启用变量」+「任务专属勾选变量」+「脚本内export语句」
• 最终生成的 env 对象传入 spawn('node', [...], {env})，完成注入

六、可视化：青龙环境变量生效全流程（Mermaid流程图）

flowchart LR
  A[用户写config.sh或docker -e] -->|❌ 无效路径| B[宿主机Shell环境]
  C[Web UI添加/ql env set] --> D[写入db.sqlite]
  D --> E{点击「更新」？}
  E -->|是| F[触发EVENT_ENV_UPDATED]
  E -->|否| G[内存env缓存未刷新]
  F --> H[service/cron.js清空缓存]
  H --> I[getTaskEnv获取合并后env]
  I --> J[spawn时注入env对象]
  K[任务编辑页勾选JD_COOKIE] --> I
  L[脚本内export JD_COOKIE=\"$JD_COOKIE\"] --> I
  J --> M[任务读取到变量]

七、高阶陷阱：容器化部署中的隐性冲突

当使用 docker-compose.yml 时，以下组合将导致静默失败：

• ❌ environment: - JD_COOKIE=xxx + Web端同时存在同名变量 → Web端值被覆盖（因Docker env优先级高于青龙DB）
• ❌ env_file: .env 中定义 JD_COOKIE → 若文件含BOM或换行符，青龙解析为 "JD_COOKIE\r" → 大小写+不可见字符双重失效
• ✅ 正确解法：容器仅传 QL_WS_PORT/QL_LOGIN_SECRET 等青龙自身配置；业务变量100%交由Web/API管理

八、审计建议：面向SRE的自动化巡检脚本

将以下检查项集成至Zabbix或Prometheus Alertmanager：

# 检查项1：未重载变量数
ql env list | jq '[.data[] | select(.status == 0)] | length'

# 检查项2：关键变量缺失率
for var in JD_COOKIE JD_USER_AGENT; do 
  ql env get "$var" >/dev/null || echo "ALERT: $var missing"
done

# 检查项3：任务绑定率（需jq 1.6+）
ql crontab list | jq '[.data[] | select(.envs | index("JD_COOKIE") // false == false)] | length'

九、演进视角：青龙v3.x对环境变量的重构方向

根据GitHub PR #3287 和 Roadmap v3.0草案，未来将引入：

• 命名空间隔离：支持 namespace: jd 级别变量作用域，避免跨脚本污染
• 动态继承策略：任务可配置 inherit: ["global", "group:jdfactory"]，替代手动勾选
• Secret Backend集成：对接Vault/KMS，变量值加密存储于DB，运行时按需解密注入
• 审计日志增强：记录每次 env.set/crontab.update 的操作者IP与UA

十、结语：超越“填坑”，构建可验证的自动化治理闭环

真正的稳定性不来自单次修复，而源于将「变量生命周期」纳入GitOps管控：用 envs.json 作为IaC声明文件，通过GitHub Action自动执行 ql env import && ql env reload && ql crontab bind-all，配合每日巡检报告推送企业微信。这正是资深SRE与初级运维的本质分水岭。

```