From e45d5ce2025dc00f34e1f2a511c29e710586b864 Mon Sep 17 00:00:00 2001
From: zhulinsen <42829555+ZhuLinsen@users.noreply.github.com>
Date: Mon, 24 Aug 2026 23:20:56 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8D=20Linux=20=E5=88=86?=
 =?UTF-8?q?=E4=BA=AB=E5=9B=BE=E4=B8=AD=E6=96=87=E7=BC=BA=E5=A4=B1=20(#2270?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: render CJK text in Linux share images

* fix(review-feedback-2270): 补到 PR 附件或评论里，和本次渲染修复说明保持一致

* fix: preserve report language contract in share images
---
 docker/Dockerfile         |  1 +
 docs/CHANGELOG.md         |  1 +
 docs/full-guide.md        |  2 +-
 docs/full-guide_EN.md     |  2 +-
 docs/share-images.md      |  3 +++
 src/share_image.py        | 12 +++++++--
 tests/test_share_image.py | 57 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/docker/Dockerfile b/docker/Dockerfile
index e3af6822a..a80d7fe34 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -34,6 +34,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     gosu \
     wkhtmltopdf \
     fontconfig \
+    fonts-noto-cjk \
     libjpeg62-turbo \
     libxrender1 \
     libxext6 \
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index ec25157c6..8e4193f8e 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- [修复] Linux/Docker 分享图补齐 Noto CJK 字体与中韩文字体栈，避免 PNG 只显示数字和英文、中文或韩文内容消失。
 <!-- 新条目格式：- [类型] 描述（类型取值：新功能/改进/修复/文档/测试/chore）-->
 <!-- 每条独立一行追加到本段末尾，无需分类标题，合并时冲突最小 -->
 
diff --git a/docs/full-guide.md b/docs/full-guide.md
index e0a60decc..3b488559b 100644
--- a/docs/full-guide.md
+++ b/docs/full-guide.md
@@ -1269,7 +1269,7 @@ PUSHOVER_API_TOKEN=your_api_token
 1. **imgkit**：已包含在 `requirements.txt`，执行 `pip install -r requirements.txt` 时会自动安装
 2. **wkhtmltopdf**（默认引擎）：系统级依赖，需手动安装：
    - **macOS**：`brew install wkhtmltopdf`
-   - **Debian/Ubuntu**：`apt install wkhtmltopdf`
+   - **Debian/Ubuntu**：`apt install wkhtmltopdf fonts-noto-cjk`（用于正确渲染项目支持的中文和韩文报告）
 3. **markdown-to-file**（可选，emoji 支持更好）：`npm i -g markdown-to-file`，并设置 `MD2IMG_ENGINE=markdown-to-file`
 4. **Playwright**（可选，适合 Web 服务）：在 `apps/dsa-web` 执行 `npm ci` 和 `npx playwright install chromium`，并设置 `MD2IMG_ENGINE=playwright`
 
diff --git a/docs/full-guide_EN.md b/docs/full-guide_EN.md
index 1e6bf8f7c..1d107fbc0 100644
--- a/docs/full-guide_EN.md
+++ b/docs/full-guide_EN.md
@@ -126,7 +126,7 @@ Go to your forked repo → `Settings` → `Secrets and variables` → `Actions`
 | `SAVE_CONTEXT_SNAPSHOT` | Whether to persist analysis-history `context_snapshot`; defaults to `true`. Set to `false` or use `--no-context-snapshot` to stop persisting the full snapshot | Optional |
 | `MARKDOWN_TO_IMAGE_CHANNELS` | Notification channels that receive report images: telegram,wechat,custom,email,slack | Optional |
 | `MARKDOWN_TO_IMAGE_MAX_CHARS` | Skip image conversion above this Markdown length (default 15000) | Optional |
-| `MD2IMG_ENGINE` | Image renderer: `wkhtmltoimage` (default), `markdown-to-file`, or `playwright` | Optional |
+| `MD2IMG_ENGINE` | Image renderer: `wkhtmltoimage` (default), `markdown-to-file`, or `playwright`. Debian/Ubuntu deployments using `wkhtmltoimage` should install both `wkhtmltopdf` and `fonts-noto-cjk` so supported Chinese and Korean report text renders correctly | Optional |
 | `SHARE_IMAGE_XIAOHONGSHU_URL` | Xiaohongshu profile URL shown in share images; empty disables the link | Optional |
 | `SHARE_IMAGE_XIAOHONGSHU_HANDLE` | Xiaohongshu nickname shown in share images; when all Xiaohongshu settings are empty, uses bundled nickname `@霸天土小豆` | Optional |
 | `SHARE_IMAGE_XIAOHONGSHU_QR_PATH` | QR image path, absolute or relative to the project root; when all Xiaohongshu settings are empty, uses the bundled QR | Optional |
diff --git a/docs/share-images.md b/docs/share-images.md
index 87fa86244..18a24f811 100644
--- a/docs/share-images.md
+++ b/docs/share-images.md
@@ -22,6 +22,9 @@
 
 `MARKDOWN_TO_IMAGE_CHANNELS`、`MD2IMG_ENGINE`、`MARKDOWN_TO_IMAGE_MAX_CHARS` 继续控制哪些通知渠道转图、使用哪个引擎以及最大输入长度。转换失败时仍回退为文本通知。
 
+分享图需要运行环境提供对应语言字体。官方 Docker 镜像已内置 Noto CJK 字体；Debian/Ubuntu 源码部署使用默认 `wkhtmltoimage` 引擎时，应安装 `wkhtmltopdf fonts-noto-cjk`。如果只安装转图工具而缺少 CJK 字体，中文或韩文可能在 PNG 中消失，只剩数字、英文和边框。
+`fonts-noto-cjk` 是 Debian 字体包名，不代表新增日文报告语言。项目的报告输出仍只支持 `REPORT_LANGUAGE=zh|en|ko`；日股个股和日本市场复盘中的日文原生名称由通用 Noto CJK fallback 覆盖，页面语言仍跟随所选报告语言，不会根据 `7203.T` 或 `region=jp` 切换成未支持的 `ja` 输出。
+
 小红书品牌使用以下可选配置。全部留空时展示仓库内置二维码及昵称 `@霸天土小豆`；配置任一自定义值后仅使用这组自定义品牌信息，避免把自定义账号与默认二维码混合：
 
 ```dotenv
diff --git a/src/share_image.py b/src/share_image.py
index ad121574d..9bbb4211b 100644
--- a/src/share_image.py
+++ b/src/share_image.py
@@ -365,6 +365,12 @@ def _poster_text(language: str, key: str) -> str:
     return _POSTER_TEXT.get(language, _POSTER_TEXT["zh"]).get(key, _POSTER_TEXT["zh"].get(key, key))
 
 
+def _poster_html_language(language: str) -> str:
+    """Map the supported report language, not the market region, to HTML lang."""
+
+    return {"zh": "zh-CN", "en": "en", "ko": "ko"}.get(language, "zh-CN")
+
+
 def _poster_label(language: str, label: str) -> str:
     translated = _POSTER_LABELS.get(language, {}).get(label)
     if translated:
@@ -2111,7 +2117,7 @@ def build_share_image_html(
     poster_branding = branding or ShareImageBranding()
 
     return f"""<!DOCTYPE html>
-<html lang="{'en' if language == 'en' else 'ko' if language == 'ko' else 'zh-CN'}">
+<html lang="{_poster_html_language(language)}">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=1080, initial-scale=1">
@@ -2119,7 +2125,9 @@ def build_share_image_html(
   <style>
     * {{ box-sizing: border-box; }}
     html, body {{ margin: 0; width: 1080px; background: #eef4fd; }}
-    body {{ color: #081b40; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "PingFang SC", "Microsoft YaHei", Arial, sans-serif; font-size: 22px; line-height: 1.5; -webkit-font-smoothing: antialiased; }}
+    body {{ color: #081b40; font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "Segoe UI", "Noto Sans CJK SC", "Noto Sans CJK KR", Arial, sans-serif; font-size: 22px; line-height: 1.5; -webkit-font-smoothing: antialiased; }}
+    html[lang="zh-CN"] body {{ font-family: "Noto Sans CJK SC", "Noto Sans SC", "PingFang SC", "Microsoft YaHei", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif; }}
+    html[lang="ko"] body {{ font-family: "Noto Sans CJK KR", "Noto Sans KR", "Apple SD Gothic Neo", "Malgun Gothic", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif; }}
     .poster {{ width: 1080px; padding: 38px 34px 24px; border: 1px solid #aebdd4; border-radius: 28px; background: radial-gradient(circle at 92% 6%, rgba(48,123,255,.15), transparent 260px), linear-gradient(180deg,#fff 0%,#fbfdff 78%,#eef5ff 100%); }}
     .poster-header {{ display: table; width: 100%; margin-bottom: 28px; }}
     .brand, .meta {{ display: table-cell; vertical-align: middle; }}
diff --git a/tests/test_share_image.py b/tests/test_share_image.py
index 9af7fb3e2..10d9f3b49 100644
--- a/tests/test_share_image.py
+++ b/tests/test_share_image.py
@@ -1967,3 +1967,60 @@ def test_desktop_backend_build_scripts_bundle_share_image_assets():
     for relative_path in ("scripts/build-backend.ps1", "scripts/build-backend-macos.sh"):
         content = (root / relative_path).read_text(encoding="utf-8")
         assert "src/assets/share_image" in content
+
+
+def test_share_image_declares_supported_cjk_fonts_and_docker_installs_them():
+    html = build_share_image_html(
+        "# 贵州茅台 600519 分析报告\n\n## 核心判断\n\n- 趋势偏多\n",
+        generated_on=date(2026, 8, 24),
+    )
+
+    assert 'html[lang="zh-CN"] body' in html
+    assert '"Noto Sans CJK SC"' in html
+    assert 'html[lang="ko"] body' in html
+    assert '"Noto Sans CJK KR"' in html
+
+    dockerfile = (
+        Path(__file__).resolve().parents[1] / "docker" / "Dockerfile"
+    ).read_text(encoding="utf-8")
+    assert "fonts-noto-cjk \\" in dockerfile
+
+
+def test_japanese_stock_share_image_uses_english_report_cjk_fallback():
+    html = build_share_image_html(
+        "# トヨタ自動車 7203.T Analysis Report\n\n## Core Conclusion\n\n- Bullish trend.\n",
+        generated_on=date(2026, 8, 24),
+        structured_payload={
+            "code": "7203.T",
+            "name": "トヨタ自動車",
+            "report_language": "en",
+        },
+    )
+
+    assert 'class="poster stock"' in html
+    assert '<html lang="en">' in html
+    assert '"Segoe UI", "Noto Sans CJK SC", "Noto Sans CJK KR"' in html
+    assert '"Noto Sans CJK SC"' in html
+    assert "トヨタ自動車" in html
+
+
+def test_japanese_market_share_image_uses_korean_report_font_contract():
+    html = build_share_image_html(
+        "# 日股市场复盘\n\n## 主要指数\n\n- 日経平均株価上涨。\n",
+        generated_on=date(2026, 8, 24),
+        structured_payload={
+            "kind": "market_review",
+            "region": "jp",
+            "report_language": "ko",
+            "title": "일본 시장 리뷰",
+            "indices": [
+                {"name": "日経平均株価", "current": 42123.45, "change_pct": 0.8},
+            ],
+        },
+    )
+
+    assert 'class="poster market"' in html
+    assert '<html lang="ko">' in html
+    assert 'html[lang="ko"] body' in html
+    assert '"Noto Sans CJK KR"' in html
+    assert "日経平均株価" in html