fix(issue-1771): chore(docker):-raise-default-compose-mem (#1774)

docker/docker-compose.yml

@@ -47,13 +47,14 @@ x-common: &common
     options:
       max-size: "10m"
       max-file: "3"
-  # 资源限制
+  # 资源限制：完整分析建议 1G+；512M 仅适合轻量 Web/API、单股、低并发场景，
+  # 且建议设置 MAX_WORKERS=1 并避免同时启动 analyzer 和 server。
   deploy:
     resources:
       limits:
-        memory: 512M
+        memory: 1G
       reservations:
-        memory: 256M
+        memory: 512M
 
 services:
   # 定时任务模式

docs/CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 - [新功能] #1595 P1.5 新增 Provider Cache Capability Registry，按 provider、api surface、gateway 和 verification status 建模 prompt cache 能力，未知 OpenAI-compatible route 默认 telemetry only。
 - [改进] #1595 P1 新增 prompt cache telemetry / analysis-path hints / diagnostics 最小配置，默认不改变 provider 请求 shape，并复用 LLM usage HMAC secret 做 domain-separated cache hint 派生。
+- [改进] 将 Docker Compose 默认内存建议从 512M 提升到 1G，并补充低配部署说明。
 <!-- 新条目格式：- [类型] 描述（类型取值：新功能/改进/修复/文档/测试/chore）-->
 <!-- 每条独立一行追加到本段末尾，无需分类标题，合并时冲突最小 -->
 

docs/DEPLOY.md

@@ -59,6 +59,16 @@ docker-compose -f ./docker/docker-compose.yml ps
 
 > 不知道怎么访问？→ [云服务器 Web 界面访问指南](deploy-webui-cloud.md)
 
+### 3.1 资源建议
+
+默认 `docker/docker-compose.yml` 为每个服务设置 `limits.memory: 1G`、`reservations.memory: 512M`，这是完整分析场景的推荐起点。
+
+- 最低可尝试：`512M`，仅适合轻量 Web/API、单股、低并发场景，建议设置 `MAX_WORKERS=1`。
+- 推荐：`1G`，适合单独运行 `server` 或 `analyzer` 的常规分析。
+- 高负载：`2G+`，适合同时启动 `server + analyzer`、多股票、默认 `MAX_WORKERS=3`、大盘复盘、新闻扩展、图片报告或 AlphaSift。
+
+如果只能使用 `512M`，请避免同时启动 `server` 和 `analyzer`，并关闭非必要的大盘复盘、新闻扩展和图片报告能力。
+
 ### 4. 常用管理命令
 
 ```bash
@@ -300,14 +310,18 @@ rm /opt/stock-analyzer/data/*.lock
 
 ### 4. 内存不足
 
-调整 `docker-compose.yml` 中的内存限制：
+默认 Compose 已推荐 `1G`。如果仍出现 OOM 或平台杀掉容器，请提高 `docker-compose.yml` 中的内存限制；同时跑 `server + analyzer`、多股票、大盘复盘、图片报告或 AlphaSift 时建议 `2G+`：
 ```yaml
 deploy:
   resources:
     limits:
       memory: 1G
+    reservations:
+      memory: 512M
 ```
 
+低配环境只能使用 `512M` 时，建议设置 `MAX_WORKERS=1`，只启动 `server` 或 `analyzer` 其中一个服务，并减少非必要的大盘复盘、新闻扩展和图片报告任务。
+
 ### 5. WebUI 打开后 UI 元素异常变大 / 布局错乱
 
 **症状**：能访问 8000 端口，但页面上的文字、按钮、卡片异常放大，没有正常布局。

docs/DEPLOY_EN.md

@@ -55,6 +55,16 @@ docker-compose -f ./docker/docker-compose.yml logs -f
 docker-compose -f ./docker/docker-compose.yml ps
 ```
 
+### 3.1 Resource Recommendations
+
+The default `docker/docker-compose.yml` sets `limits.memory: 1G` and `reservations.memory: 512M` for each service. Treat this as the recommended starting point for full analysis workloads.
+
+- Minimum trial: `512M`, only for lightweight Web/API usage, single-stock runs, and low concurrency. Set `MAX_WORKERS=1`.
+- Recommended: `1G`, suitable for normal analysis when running either `server` or `analyzer`.
+- Heavy workloads: `2G+`, suitable when running `server + analyzer` together, multi-stock analysis, default `MAX_WORKERS=3`, market review, news expansion, image reports, or AlphaSift.
+
+If you can only use `512M`, avoid starting both `server` and `analyzer`, and disable non-essential market review, news expansion, and image report features.
+
 ### 4. Common Management Commands
 
 ```bash
@@ -288,14 +298,18 @@ rm /opt/stock-analyzer/data/*.lock
 
 ### 4. Insufficient memory
 
-Adjust memory limits in `docker-compose.yml`:
+The default Compose recommendation is already `1G`. If the container still hits OOM or is killed by the platform, raise the memory limit in `docker-compose.yml`; use `2G+` when running `server + analyzer` together, multi-stock analysis, market review, image reports, or AlphaSift:
 ```yaml
 deploy:
   resources:
     limits:
       memory: 1G
+    reservations:
+      memory: 512M
 ```
 
+For a constrained `512M` deployment, set `MAX_WORKERS=1`, start only one of `server` or `analyzer`, and reduce non-essential market review, news expansion, and image report tasks.
+
 ---
 
 ## Quick Migration

docs/docker/zeabur-deployment.md

@@ -65,6 +65,16 @@ FastAPI 会自动托管 `static/` 目录下的前端资源。前端打包输出
 Dockerfile 已采用多阶段构建，前端会在镜像构建时自动打包。
 如需覆盖默认静态资源，可在宿主机手动构建并挂载到容器内 `/app/static`。
 
+### 2.5 资源配置建议
+
+Zeabur 服务建议从 `1G` 内存起步；`512M` 仅适合轻量 Web/API、单股、低并发场景，并建议设置 `MAX_WORKERS=1`。
+
+- 最低可尝试：`512M`，不要同时运行多个重型任务。
+- 推荐：`1G`，适合单服务常规分析。
+- 高负载：`2G+`，适合同时运行 Web/API 与定时分析、多股票、大盘复盘、新闻扩展、图片报告或 AlphaSift。
+
+如果只能使用 `512M`，请避免同时部署等价于 `server + analyzer` 的多服务组合，并关闭非必要的大盘复盘、新闻扩展和图片报告能力。
+
 ## 3. 配置启动命令
 
 ### 3.1 支持的启动模式
@@ -331,6 +341,7 @@ zeabur exec <服务名> python -c "import requests; print(requests.get('https://
 4. **定期备份数据**：定期下载 `/app/data` 目录的内容进行备份
 5. **使用合适的启动模式**：根据需求选择合适的启动命令
 6. **监控服务状态**：定期检查服务状态和日志
+7. **按负载配置内存**：完整分析推荐 `1G` 起步；`512M` 低配环境设置 `MAX_WORKERS=1`，高负载场景使用 `2G+`
 
 ## 14. 联系方式
 

docs/full-guide.md

@@ -474,6 +474,8 @@ docker-compose -f ./docker/docker-compose.yml up -d            # 同时启动两
 docker-compose -f ./docker/docker-compose.yml logs -f server
 ```
 
+默认 Compose 为每个服务设置 `limits.memory: 1G`、`reservations.memory: 512M`。`512M` 仅建议用于轻量 Web/API、单股、低并发场景，并将 `MAX_WORKERS=1`；常规完整分析建议 `1G`，同时启动 `server + analyzer`、多股票、大盘复盘、新闻扩展、图片报告或 AlphaSift 建议 `2G+`。如果只能使用 `512M`，请避免同时启动两个服务并减少重型功能。
+
 ### 直接拉官方镜像运行
 
 如果你不打算在目标机器上保留源码，可以直接拉取官方镜像：
@@ -532,6 +534,12 @@ x-common: &common
     - ../logs:/app/logs
     - ../reports:/app/reports
     - ../strategies:/app/strategies:ro
+  deploy:
+    resources:
+      limits:
+        memory: 1G
+      reservations:
+        memory: 512M
 
 services:
   # 定时任务模式

docs/full-guide_EN.md

@@ -405,6 +405,8 @@ docker-compose -f ./docker/docker-compose.yml up -d            # Start both mode
 docker-compose -f ./docker/docker-compose.yml logs -f server
 ```
 
+The default Compose file sets `limits.memory: 1G` and `reservations.memory: 512M` for each service. Use `512M` only for lightweight Web/API usage, single-stock runs, and low concurrency with `MAX_WORKERS=1`; use `1G` for normal full analysis, and `2G+` when running `server + analyzer` together, multi-stock analysis, market review, news expansion, image reports, or AlphaSift. If constrained to `512M`, avoid starting both services and reduce heavy features.
+
 ### Run Official Images Directly
 
 If you do not want to keep the source tree on the target machine, you can run the published image directly:
@@ -463,6 +465,12 @@ x-common: &common
     - ../logs:/app/logs
     - ../reports:/app/reports
     - ../strategies:/app/strategies:ro
+  deploy:
+    resources:
+      limits:
+        memory: 1G
+      reservations:
+        memory: 512M
 
 services:
   # Scheduled task mode

tests/test_docker_entrypoint.py

@@ -60,6 +60,35 @@ def test_docker_compose_injects_env_without_single_file_env_mount() -> None:
     assert "../longbridge_tokens:/home/dsa/.longbridge" in common["volumes"]
 
 
+def test_docker_compose_default_memory_recommendation_is_not_512m() -> None:
+    compose_text = (REPO_ROOT / "docker" / "docker-compose.yml").read_text(encoding="utf-8")
+    compose = yaml.safe_load(compose_text)
+    resources = compose["x-common"]["deploy"]["resources"]
+
+    assert resources["limits"]["memory"] == "1G"
+    assert resources["reservations"]["memory"] == "512M"
+    assert "512M" in compose_text
+    assert "MAX_WORKERS=1" in compose_text
+
+
+def test_docker_memory_guides_describe_resource_profiles() -> None:
+    doc_paths = (
+        "docs/DEPLOY.md",
+        "docs/DEPLOY_EN.md",
+        "docs/full-guide.md",
+        "docs/full-guide_EN.md",
+        "docs/docker/zeabur-deployment.md",
+    )
+
+    for doc_path in doc_paths:
+        doc = (REPO_ROOT / doc_path).read_text(encoding="utf-8")
+
+        assert "512M" in doc
+        assert "1G" in doc
+        assert "2G+" in doc
+        assert "MAX_WORKERS=1" in doc
+
+
 def test_docker_guides_do_not_recommend_single_file_env_bind_mount() -> None:
     forbidden_mount_patterns = [
         r"\$\(pwd\)/\.env:/app/\.env",

tests/test_provider_cache.py

@@ -359,7 +359,11 @@ def test_litellm_openai_prompt_cache_key_is_not_passed_through_without_verified_
             def log_message(self, *args):
                 return
 
-        server = HTTPServer(("127.0.0.1", 0), CaptureHandler)
+        try:
+            server = HTTPServer(("127.0.0.1", 0), CaptureHandler)
+        except PermissionError as exc:
+            print(f"LOCAL_SOCKET_UNAVAILABLE={exc}")
+            raise SystemExit(78)
         thread = threading.Thread(target=server.serve_forever, daemon=True)
         thread.start()
         try:
@@ -392,6 +396,8 @@ def test_litellm_openai_prompt_cache_key_is_not_passed_through_without_verified_
     )
     if completed.returncode == 77:
         pytest.skip("litellm is not installed")
+    if completed.returncode == 78:
+        pytest.skip("local socket creation is not permitted in this environment")
     assert completed.returncode == 0, completed.stdout + completed.stderr
     captured_line = next(
         (line for line in completed.stdout.splitlines() if line.startswith("CAPTURED_BODY=")),