fix(issue-1261): [bug]-docker-部署启动失败 (#1262)

Author: ZhuLinsen

docs/CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - [文档] 更新多语言 README 首页浅色工作台 GIF，并精简功能特性表，保留原有赞助商、快速开始和推送效果结构。
 - [新功能] 通知网关新增默认关闭的进程内降噪配置，支持去重、冷却、静默时段和最低严重级别，并将每日摘要开关标记为预留能力。
 - [文档] 恢复多语言 README 新闻源配置表中推荐项的加粗样式，统一相关项目章节层级，并精简顶部导航、联系文案和尾部展示。
+- [修复] Docker 挂载的 `logs` 目录不可写时启动日志自动降级到控制台输出，并补充非 root 容器目录权限说明。
 
 ## [3.16.0] - 2026-05-10
 

docs/full-guide.md

@@ -502,6 +502,15 @@ services:
 - `./reports:/app/reports`：生成的分析报告
 - `./strategies:/app/strategies:ro`：自定义策略 YAML（只读挂载）
 
+官方 Docker 镜像默认使用容器内非 root 用户 `dsa`（UID/GID `1000:1000`）运行。首次部署或更换宿主机目录后，请确保 `data`、`logs`、`reports` 对该用户可写，否则文件日志会自动降级到控制台输出，数据库或报告写入仍可能失败：
+
+```bash
+mkdir -p data logs reports
+sudo chown -R 1000:1000 data logs reports
+```
+
+如果你通过 `--user` 或 Compose `user:` 指定了其他运行用户，请将上面的 UID/GID 替换为实际容器用户，或使用等价的 ACL / 权限策略授予写入权限。
+
 如果你需要覆盖内置静态资源，还可以额外挂载：
 
 - `./static:/app/static:ro`

docs/full-guide_EN.md

@@ -467,6 +467,15 @@ Recommended host mappings:
 - `./reports:/app/reports` for generated reports
 - `./strategies:/app/strategies:ro` for custom strategy YAML files
 
+Official Docker images run as the non-root `dsa` user inside the container (UID/GID `1000:1000`). On first deployment or after changing host directories, make sure `data`, `logs`, and `reports` are writable by that user. If `logs` is not writable, file logging falls back to console output; database or report writes may still fail until permissions are fixed:
+
+```bash
+mkdir -p data logs reports
+sudo chown -R 1000:1000 data logs reports
+```
+
+If you override the runtime user with `--user` or Compose `user:`, replace the UID/GID above with the actual container user, or grant write access with an equivalent ACL / permission policy.
+
 Optional static asset override:
 
 - `./static:/app/static:ro`

main.py

@@ -141,6 +141,22 @@ def _setup_bootstrap_logging(debug: bool = False) -> None:
         root.addHandler(handler)
 
 
+def _setup_runtime_logging(log_dir: str, debug: bool = False) -> bool:
+    """Switch to configured logging, falling back to console on file I/O errors."""
+    try:
+        setup_logging(log_prefix="stock_analysis", debug=debug, log_dir=log_dir)
+        return True
+    except OSError as exc:
+        logger.warning(
+            "文件日志初始化失败，已降级为控制台日志输出；日志目录 %r 当前不可写或不可创建: %s。"
+            "Docker bind mount 请确保宿主机 data/logs/reports 目录可由容器内 UID 1000 写入，"
+            "例如执行 `sudo chown -R 1000:1000 data logs reports` 后重启容器。",
+            log_dir,
+            exc,
+        )
+        return False
+
+
 def _get_stock_analysis_pipeline():
     """Lazily import StockAnalysisPipeline for external consumers.
 
@@ -767,7 +783,7 @@ def main() -> int:
 
     # 配置日志（输出到控制台和文件）
     try:
-        setup_logging(log_prefix="stock_analysis", debug=args.debug, log_dir=config.log_dir)
+        _setup_runtime_logging(config.log_dir, debug=args.debug)
     except Exception as exc:
         logger.exception("切换到配置日志目录失败: %s", exc)
         return 1

tests/test_main_schedule_mode.py

@@ -491,6 +491,40 @@ def test_bootstrap_logging_failure_does_not_block_startup(self) -> None:
         self.assertEqual(exit_code, 0)
         run_mock.assert_called_once()
 
+    def test_runtime_file_logging_permission_error_falls_back_to_console(self) -> None:
+        """Configured file logging failures should not prevent Docker startup."""
+        import io
+
+        args = self._make_args()
+        config = self._make_config(log_dir="/app/logs")
+        capture_stream = io.StringIO()
+        capture_handler = logging.StreamHandler(capture_stream)
+        capture_handler.setLevel(logging.DEBUG)
+        capture_handler.setFormatter(logging.Formatter("%(message)s"))
+
+        root_logger = logging.getLogger()
+
+        with patch("main.parse_arguments", return_value=args), \
+             patch("main.get_config", return_value=config), \
+             patch(
+                 "main.setup_logging",
+                 side_effect=PermissionError("/app/logs/stock_analysis_20260511.log"),
+             ), \
+             patch("main.run_full_analysis") as run_mock:
+            root_logger.addHandler(capture_handler)
+            try:
+                exit_code = main.main()
+            finally:
+                root_logger.removeHandler(capture_handler)
+                capture_handler.close()
+
+        self.assertEqual(exit_code, 0)
+        run_mock.assert_called_once()
+        output = capture_stream.getvalue()
+        self.assertIn("文件日志初始化失败，已降级为控制台日志输出", output)
+        self.assertIn("/app/logs", output)
+        self.assertIn("sudo chown -R 1000:1000 data logs reports", output)
+
     def test_run_full_analysis_import_failure_propagates(self) -> None:
         """P1: import failures in run_full_analysis must propagate, not be swallowed."""
         args = self._make_args()