Skip to content

fix: render repository images in project READMEs - #958

Open
TyreeZhao wants to merge 3 commits into
chaitin:mainfrom
TyreeZhao:fix/readme-repository-images
Open

fix: render repository images in project READMEs#958
TyreeZhao wants to merge 3 commits into
chaitin:mainfrom
TyreeZhao:fix/readme-repository-images

Conversation

@TyreeZhao

@TyreeZhao TyreeZhao commented Aug 1, 2026

Copy link
Copy Markdown

问题

项目「信息」页中的 README 无法展示仓库内相对路径图片:Markdown 图片显示为破图,原生 HTML 图片语法显示为文本。

Closes #957

修改范围

后端

  • 新增受现有项目鉴权保护的 GET /api/v1/users/projects/{id}/tree/media 接口。
  • 复用项目 blob 读取逻辑,支持按 pathref 获取 README 图片。
  • 仅允许 PNG、JPEG、GIF、WebP,并依据文件内容嗅探真实 Content-Type
  • 支持读取超过 GitHub Contents API 1 MiB 内联限制的仓库图片。
  • 媒体读取上限为 10 MiB:已知大小时提前拒绝,未知大小时使用有界读取,避免无上限缓冲。
  • 普通 blob 请求继续沿用原有读取路径,避免扩大既有接口的读取范围。
  • 增加 ETagprivate, no-cache、inline disposition 与 nosniff 响应头。

前端

  • 为通用 Markdown 组件增加可选 resolveImageUrl 扩展点,不改变其他调用方的默认行为。
  • 项目 README 基于 README 所在目录解析相对图片,并保留项目 ID 与当前分支。
  • 支持父目录、仓库根路径、中文、空格和外部 HTTP(S) 图片。
  • 拒绝 data:javascript:、反斜杠和越出仓库根目录的路径。
  • 在项目 README 场景启用经现有 rehype-sanitize 净化后的原生 HTML,以支持 <details> / <img>
  • 同步 Swagger 文档与生成的前端 Blob API 契约(format: "blob")。

测试证据

  • go test ./pkg/git/github ./biz/project/handler/v1
  • go test -race ./pkg/git/... ./biz/project/...
  • npx --yes tsx --test test/readme-media.test.ts ✅(6/6)
  • npm run lint
  • npm run build
  • jq empty backend/docs/swagger.json
  • Chrome 端到端验证 ✅
    • 两张 Markdown 相对图片均解码为 1440 × 1000
    • 一张原生 HTML 图片解码为 390 × 3390
    • 测试样本扩展名为 .png、实际内容为 JPEG,服务端正确返回 image/jpeg

构建仍会显示仓库环境已有的 Node.js 版本建议及大 chunk 提示,构建退出码为 0,与本次修改无关。

截图

修复后:Markdown 相对图片正常展示:
clipboard

修复后:经安全净化的原生 HTML <img> 正常展示:

clipboard

Resolve relative README image paths through an authenticated media endpoint with content validation and caching. Support sanitized HTML images and cover unsafe paths and media types.\n\nRefs chaitin#957
Support GitHub repository images larger than 1 MiB without unbounded buffering, revalidate mutable branch images with ETags, and cover content sniffing and download limits.\n\nRefs chaitin#957
Preserve the existing GitHub blob behavior unless an explicit media limit is supplied, document all supported image response types, and add the generated binary API contract and integration wiring test.

Refs chaitin#957
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] 项目 README 中引用的仓库内图片无法正常展示

1 participant