fix: Docker 部署启动失败 (#1261)

[ZhuLinsen]

PR Type

• fix
• feat
• refactor
• docs
• chore
• test

Background And Problem

• 当前问题：让 Docker 部署在挂载的 logs 目录无写权限时不会因日志文件初始化失败而直接启动失败，并给出可操作的权限说明。
• 影响范围：本次改动涉及 5 个文件，Diff 为 +70 / -1。
• 触发来源：Issue 自动执行（Issue [Bug] Docker 部署启动失败 #1261）。

Scope Of Change

• docs/CHANGELOG.md
• docs/full-guide.md
• docs/full-guide_EN.md
• main.py
• tests/test_main_schedule_mode.py

Documentation And Changelog

• 已同步更新文档/变更记录：docs/CHANGELOG.md, docs/full-guide.md, docs/full-guide_EN.md。

Issue Link

Closes #1261

Verification Commands And Results

./scripts/ci_gate.sh flake8
./scripts/ci_gate.sh offline-tests

关键输出/结论 / Key output & conclusion:

• lint:PASS, test:PASS

Compatibility And Risk

• High：涉及 docs/CHANGELOG.md, docs/full-guide.md, docs/full-guide_EN.md, main.py, tests/test_main_schedule_mode.py，请重点审查变更范围、验证覆盖与发布影响。
• 前提假设：
  • v3.16.0 镜像可能已切换为非 root 用户运行，宿主机 bind mount 的 logs 目录权限未授予容器内运行用户写入权限。
  • 最小修复优先放在启动日志初始化的降级逻辑中：文件日志不可写时保留 stderr/console logging，并输出明确诊断信息。
  • 如果当前实现已经有降级逻辑，需要核对是否仍存在未捕获的 PermissionError 或后续文件 handler 创建路径。
  • Dockerfile 无法在构建阶段修复运行时 bind mount 的宿主机目录权限，文档需补充 chown/chmod 或用户映射建议。

Rollback Plan

• git revert <merge-commit> 回滚本 PR 提交，重点确认 docs/CHANGELOG.md, docs/full-guide.md, docs/full-guide_EN.md, main.py 恢复正常。

Acceptance Criteria

• 使用只读或不可写的 /app/logs 挂载启动服务时，进程不因 PermissionError 退出。
• 日志系统在文件日志不可用时自动降级到控制台输出，并明确提示当前日志目录不可写及处理建议。
• 正常可写 logs 目录下仍生成 stock_analysis_*.log，现有本地运行行为不回归。
• Docker 部署文档包含非 root 容器运行时 data/logs/reports 挂载目录权限要求。
• docs/CHANGELOG.md 的 [Unreleased] 按扁平格式新增修复记录。

Notes

• Risk is marked as high. Please review scope, validation coverage, and release impact carefully.

Checklist

• 本 PR 有明确动机和业务价值 / This PR has a clear motivation and value
• 已提供可复现的验证命令与结果 / Reproducible verification commands and results are included
• 已评估兼容性与风险 / Compatibility and risk have been assessed
• 已提供回滚方案 / A rollback plan is provided
• 已同步更新相关文档与 docs/CHANGELOG.md，并在 PR 描述中说明文档落点 / Relevant docs and docs/CHANGELOG.md are updated, and the documentation location is stated in this PR

[github-actions]

🤖 自动审查报告

项目	结果
📊 变更文件	5 个
➕ 新增行数	70 行
➖ 删除行数	1 行
🔍 静态检查	✅ 通过
🧠 AI 审查	✅ 已完成

📁 修改的文件

• 📝 docs/CHANGELOG.md (+1/-0)
• 📝 docs/full-guide.md (+9/-0)
• 📝 docs/full-guide_EN.md (+9/-0)
• 📝 main.py (+17/-1)
• 📝 tests/test_main_schedule_mode.py (+34/-0)

---

🧠 AI 代码审查意见

结论

Ready to Merge

结构化审查结果

必要性

• 通过
• 理由: PR 解决了 Docker 部署中 logs 目录无写权限导致启动失败的核心问题（Issue [Bug] Docker 部署启动失败 #1261），并提供了健壮的降级机制和清晰的权限说明，具有明确的业务价值和用户体验提升。

关联性

• 通过
• 证据: PR 描述中明确提及 Closes #1261。

类型

• 建议类型: fix
• 理由: 变更内容旨在修复一个实际存在的部署问题，与 PR 类型 fix 完全匹配。

描述完整性

• 完整
• 理由:
  • 包含背景、问题、影响范围和触发来源。
  • 明确列出了变更文件范围。
  • 提供了详细的 Verification Commands And Results，并说明 lint:PASS, test:PASS，且提到了 ci_gate.sh flake8 和 ci_gate.sh offline-tests。
  • 详细评估了兼容性与风险，并给出了前提假设。
  • 提供了清晰的回滚方案。
  • 列出了明确的验收标准，且在 Notes 中重申了高风险项。
  • docs/CHANGELOG.md 和 docs/full-guide.md / docs/full-guide_EN.md 的更新情况已在 Documentation And Changelog 和 Checklist 中说明。
  • CI 检查状态显示 py_compile 和 flake8 均已通过。

风险级别

• 高
• 关键风险: 变更涉及核心启动逻辑和日志初始化流程，虽然有降级处理，但如果处理不当可能影响服务的稳定运行。同时，Docker 部署文档的修改也需要确保其准确性和易理解性。PR 描述中已充分评估并提及此高风险。

必改项

• 无

建议项

• 无 (本次 PR 描述、代码和文档更新质量很高，已充分满足所有审查要求。)

---

详细审查

1. 代码变更 (main.py):

   • 新增 _setup_runtime_logging 函数，封装了原 main 函数中 setup_logging 的调用。
   • 在 _setup_runtime_logging 中，通过 try...except OSError 捕获文件日志初始化可能抛出的权限错误，并回退到控制台日志输出。
   • 错误信息清晰明了，包含具体的问题描述和详细的 chown -R 1000:1000 data logs reports 修复建议，非常有助于用户排查和解决问题。
   • PermissionError 是 OSError 的子类，因此捕获 OSError 是正确的。
   • main() 函数中已将 setup_logging 调用替换为 _setup_runtime_logging。
   • 代码逻辑合理，满足了在文件日志不可写时降级到控制台日志输出的需求。

2. 测试变更 (tests/test_main_schedule_mode.py):

   • 新增 test_runtime_file_logging_permission_error_falls_back_to_console 测试用例，通过 patch 模拟 PermissionError 发生在 setup_logging 时。
   • 测试用例验证了在这种情况下，main() 函数的退出码为 0（即不因权限错误而崩溃）。
   • 通过捕获标准输出来断言控制台日志中是否包含了预期的降级提示和修复建议，有效验证了降级和用户提示功能。
   • 测试覆盖了关键的异常处理场景。

3. 文档变更 (docs/CHANGELOG.md, docs/full-guide.md, docs/full-guide_EN.md):

   • docs/CHANGELOG.md 已在 [Unreleased] 部分新增了修复记录 [修复] Docker 挂载的 logs 目录不可写时启动日志自动降级到控制台输出，并补充非 root 容器目录权限说明。，符合扁平格式和内容要求。
   • docs/full-guide.md 和 docs/full-guide_EN.md 都增加了关于 Docker 挂载目录权限的说明，明确指出官方镜像使用非 root 用户 dsa (UID/GID 1000:1000) 运行，并给出了 sudo chown -R 1000:1000 data logs reports 的具体修复命令。这与代码中的错误提示形成闭环，极大地提升了用户部署体验。

4. CI 检查状态:

   • 静态检查总体结果: ✅ 通过
   • Python 语法检查 (py_compile): ✅ 通过
   • Flake8 严重错误检查 (E9/F63/F7/F82): ✅ 通过
   • 所有 CI 检查均已通过。PR 描述中也提到了本地运行 ./scripts/ci_gate.sh flake8 和 ./scripts/ci_gate.sh offline-tests 均通过。

总结: 本次 PR 彻底解决了 Docker 部署中日志目录权限不足的问题，通过在代码中实现优雅降级，并同步更新了详尽的用户文档和变更日志，形成了完善的问题解决闭环。代码、测试和文档都做得非常到位，可以安全合并。

---

💡 提示: 请确保代码已通过本地测试，并遵循项目代码规范。

[Copilot]

Pull request overview

该 PR 修复了 Docker 部署场景下 logs 挂载目录不可写导致 setup_logging() 初始化日志文件失败、进而使进程启动失败的问题；通过在主入口对文件日志初始化的 OSError 做降级处理，确保仍能以控制台日志继续启动，并在文档中补充非 root 运行时的宿主机目录权限要求。

Changes:

• 在 main.py 增加运行时日志初始化包装 _setup_runtime_logging()：文件日志初始化遇到 OSError（含 PermissionError）时降级为控制台日志并输出可操作的权限修复提示。
• 新增单测覆盖“文件日志不可写不阻断启动”的行为，并断言降级提示文本包含关键修复指引。
• 更新完整指南（中英文）与 docs/CHANGELOG.md，补充官方镜像非 root（UID/GID 1000）运行时挂载目录权限说明与变更记录。

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
main.py	增加运行时日志初始化降级逻辑，避免 Docker 因 logs 不可写而启动失败，并输出权限修复建议。
tests/test_main_schedule_mode.py	增加回归测试，验证 setup_logging() 抛出 PermissionError 时仍可继续启动并给出提示。
docs/full-guide.md	补充非 root 容器用户（1000:1000）运行下 data/logs/reports 挂载目录权限要求与示例命令。
docs/full-guide_EN.md	同步英文文档的权限说明与示例命令。
docs/CHANGELOG.md	按 [Unreleased] 扁平格式追加一条 Docker 日志降级修复记录。

[ZhuLinsen]

评审结论

• 必要性：通过，修复 Docker 挂载 logs 目录无写权限时启动失败的问题，符合 Issue #1261 的实际故障场景。
• 是否有对应 issue：有，Closes #1261。
• PR 类型：fix，代码层面增加日志初始化降级逻辑，并补充回归测试和部署文档。
• description 完整性：完整，已覆盖背景、改动范围、文档落点、验证结果、兼容性风险、验收标准和回滚方案。
• 是否可直接合入：可，当前 CI 为 success，改动范围与问题关联清晰，未发现阻断性正确性或兼容性问题。

---

🤖 此回复由 OpenReview Bot 自动生成，仅供参考。如有疑问请 @维护者。