From cca629ff24eedfa83ace1bda026b8f3bcc483bca Mon Sep 17 00:00:00 2001 From: mumu <42829555+ZhuLinsen@users.noreply.github.com> Date: Wed, 24 Jun 2026 20:17:20 +0800 Subject: [PATCH] fix(issue-1771): chore(docker):-raise-default-compose-mem (#1774) --- docker/docker-compose.yml | 7 ++++--- docs/CHANGELOG.md | 1 + docs/DEPLOY.md | 16 +++++++++++++++- docs/DEPLOY_EN.md | 16 +++++++++++++++- docs/docker/zeabur-deployment.md | 11 +++++++++++ docs/full-guide.md | 8 ++++++++ docs/full-guide_EN.md | 8 ++++++++ tests/test_docker_entrypoint.py | 29 +++++++++++++++++++++++++++++ tests/test_provider_cache.py | 8 +++++++- 9 files changed, 98 insertions(+), 6 deletions(-) diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 5c96e856f..d515f3143 100644 --- a/docker/docker-compose.yml +++ b/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: # 定时任务模式 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 083d4278c..411fc72fc 100644 --- a/docs/CHANGELOG.md +++ b/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，并补充低配部署说明。 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 67f0efe0b..7dbdb0c24 100644 --- a/docs/DEPLOY.md +++ b/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 端口，但页面上的文字、按钮、卡片异常放大，没有正常布局。 diff --git a/docs/DEPLOY_EN.md b/docs/DEPLOY_EN.md index 202b1714d..3d79e8cec 100644 --- a/docs/DEPLOY_EN.md +++ b/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 diff --git a/docs/docker/zeabur-deployment.md b/docs/docker/zeabur-deployment.md index 3eb9e0e49..452a7a415 100644 --- a/docs/docker/zeabur-deployment.md +++ b/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. 联系方式 diff --git a/docs/full-guide.md b/docs/full-guide.md index 44cece08f..673213d64 100644 --- a/docs/full-guide.md +++ b/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: # 定时任务模式 diff --git a/docs/full-guide_EN.md b/docs/full-guide_EN.md index 3cb371a17..486994367 100644 --- a/docs/full-guide_EN.md +++ b/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 diff --git a/tests/test_docker_entrypoint.py b/tests/test_docker_entrypoint.py index b686a9bfc..0b2d14b33 100644 --- a/tests/test_docker_entrypoint.py +++ b/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", diff --git a/tests/test_provider_cache.py b/tests/test_provider_cache.py index 383da1566..4c995363a 100644 --- a/tests/test_provider_cache.py +++ b/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=")),