Files
knowledge-governance/internal/versionhistory/gitea.go
T
姚章浩 4cb5110845
build / build (push) Successful in 1m1s
fix(version-history): 页面链接改走公网 origin(抓取仍走内网)+ tag 补链接
现象(主人反馈):点「查看提交」打开是空白页。原因:链接用的是**抓取用的内网地址**
(`http://192.168.50.223:3000/...`),内网外的浏览器到不了;而公网地址
`https://gitea.zheromiku.top/...` 实测 200。另外 tag 证据里**根本没有 url**,
页面渲染出空 `href`,点下去像"没反应"。

修复:

- 新增 `VERSION_HISTORY_LINK_ORIGIN`(页面链接 origin,公网;留空 = 与抓取 origin 相同):
  抓取仍匿名走内网白名单地址,**给人点的链接**用公网 origin 拼 —— 两者本就不该共用一个地址;
  校验必须是干净的 http(s) 绝对地址。
- tag 证据补 `url`(`<link origin>/<repo>/src/tag/<name>`),并在前端**没有链接就不渲染**该按钮。
- 测试:客户端(LinkOrigin 生效 / 未配时退回 / 非法拒绝)、规则(tag 链接写入证据 / 无基址不编链接)、
  前端(有链接才渲染「查看 tag」)。

验证:make verify 15/15;真实链路重同步后库里 commit_url = `https://gitea.zheromiku.top/...`(200)、
release_tags 带 url。
2026-10-14 11:06:13 +08:00

356 lines
12 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package versionhistory
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
)
// GiteaConfig 是只读客户端的配置。**只用匿名请求**:本客户端不会携带任何凭据,
// 也不接受调用方传入任意 URL —— base 必须在白名单里,仓库只允许配置的那一个。
type GiteaConfig struct {
BaseURL string
AllowedBaseURLs []string
// LinkOrigin 是**给人看的链接**用的 origin(例如公网 https://gitea.example)。
// 抓取用内网地址、点链接的人在内网外 —— 两者必须能分开,否则页面上的链接打不开。
// 留空则与 BaseURL 相同。它只用于拼展示链接,不参与任何请求。
LinkOrigin string
Repo string
HTTPClient *http.Client
Timeout time.Duration
MaxResponseBytes int64
MaxRetries int
Sleep func(time.Duration)
PageSize int
}
// GiteaClient 只读地访问 Gitea 的提交、tag 与仓库内文件。
type GiteaClient struct {
baseURL *url.URL
linkOrigin string
repo string
client *http.Client
maxBytes int64
maxRetries int
sleep func(time.Duration)
pageSize int
}
const (
giteaDefaultTimeout = 15 * time.Second
giteaDefaultMaxBytes = 5 << 20 // 单个响应上限 5MB
giteaDefaultRetries = 3
giteaDefaultPageSize = 50 // Gitea 的 commits/tags 上限就是 50
giteaCommitURLSuffix = "/commit/"
)
// NewGiteaClient 校验并构造客户端。校验失败一律返回错误(宁可不接线)。
func NewGiteaClient(config GiteaConfig) (*GiteaClient, error) {
base, err := url.Parse(strings.TrimSpace(config.BaseURL))
if err != nil || base.Host == "" || (base.Scheme != "http" && base.Scheme != "https") {
return nil, errors.New("版本记录:Gitea base URL 非法(必须是 http(s) 绝对地址)")
}
allowed := false
for _, candidate := range config.AllowedBaseURLs {
parsed, perr := url.Parse(strings.TrimSpace(candidate))
if perr == nil && parsed.Host != "" && parsed.Scheme == base.Scheme && parsed.Host == base.Host {
allowed = true
break
}
}
if !allowed {
return nil, fmt.Errorf("版本记录:Gitea base URL %q 不在白名单里(拒绝任意 URL 请求)", config.BaseURL)
}
repo := strings.Trim(strings.TrimSpace(config.Repo), "/")
if strings.Count(repo, "/") != 1 || strings.ContainsAny(repo, " \t?#") {
return nil, errors.New("版本记录:仓库必须是 owner/name 形式")
}
maxBytes := config.MaxResponseBytes
if maxBytes <= 0 {
maxBytes = giteaDefaultMaxBytes
}
timeout := config.Timeout
if timeout <= 0 {
timeout = giteaDefaultTimeout
}
retries := config.MaxRetries
if retries <= 0 {
retries = giteaDefaultRetries
}
pageSize := config.PageSize
if pageSize <= 0 || pageSize > giteaDefaultPageSize {
pageSize = giteaDefaultPageSize
}
client := config.HTTPClient
if client == nil {
client = &http.Client{Timeout: timeout}
}
// 只允许回到同一个 host:重定向到别处一律拒绝(防 SSRF)。
sameHost := *client
sameHost.CheckRedirect = func(req *http.Request, via []*http.Request) error {
if req.URL.Scheme != base.Scheme || req.URL.Host != base.Host {
return newGiteaError(KindRedirect, 0, "版本记录:拒绝重定向到其它主机", nil)
}
return nil
}
sleep := config.Sleep
if sleep == nil {
sleep = time.Sleep
}
linkOrigin := strings.TrimRight(strings.TrimSpace(config.LinkOrigin), "/")
if linkOrigin == "" {
linkOrigin = strings.TrimRight(base.String(), "/")
} else if parsed, perr := url.Parse(linkOrigin); perr != nil || parsed.Host == "" ||
(parsed.Scheme != "http" && parsed.Scheme != "https") {
return nil, fmt.Errorf("版本记录:链接 origin %q 非法(必须是 http(s) 绝对地址)", config.LinkOrigin)
}
return &GiteaClient{baseURL: base, linkOrigin: linkOrigin, repo: repo, client: &sameHost,
maxBytes: maxBytes, maxRetries: retries, sleep: sleep, pageSize: pageSize}, nil
}
// PageSize 是抓取页大小(外层据此做完整性对账)。
func (c *GiteaClient) PageSize() int { return c.pageSize }
// CommitURLBase 给记录页拼提交链接用(**给人看的** origin + 固定仓库,不接受外部传入)。
// 抓取走内网、链接走公网 —— 两者分开,页面上的链接才点得开。
func (c *GiteaClient) CommitURLBase() string {
return c.linkOrigin + "/" + c.repo + giteaCommitURLSuffix
}
// TagURLBase 给记录页拼 tag 链接用(`<link origin>/<repo>/src/tag/`)。
func (c *GiteaClient) TagURLBase() string {
return c.linkOrigin + "/" + c.repo + "/src/tag/"
}
func (c *GiteaClient) apiURL(path string, query url.Values) string {
target := *c.baseURL
target.Path = strings.TrimRight(c.baseURL.Path, "/") + "/api/v1/repos/" + c.repo + path
target.RawQuery = query.Encode()
return target.String()
}
// get 发一次匿名 GET(**不设 Authorization 头**),带超时、响应上限与退避重试。
func (c *GiteaClient) get(ctx context.Context, rawURL string) ([]byte, http.Header, error) {
var lastErr error
for attempt := 0; attempt <= c.maxRetries; attempt++ {
if attempt > 0 {
c.sleep(time.Duration(attempt) * 500 * time.Millisecond)
}
request, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
if err != nil {
return nil, nil, newGiteaError(KindParse, 0, "版本记录:构造请求失败", err)
}
request.Header.Set("Accept", "application/json")
response, err := c.client.Do(request)
if err != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:Gitea 不可达", err)
continue
}
body, readErr := io.ReadAll(io.LimitReader(response.Body, c.maxBytes+1))
closeErr := response.Body.Close()
if readErr != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:读取响应失败", readErr)
continue
}
if closeErr != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:关闭响应失败", closeErr)
continue
}
if int64(len(body)) > c.maxBytes {
return nil, nil, newGiteaError(KindTooLarge, response.StatusCode,
fmt.Sprintf("版本记录:响应超过 %d 字节上限(已丢弃)", c.maxBytes), nil)
}
switch {
case response.StatusCode == http.StatusOK:
return body, response.Header, nil
case response.StatusCode == http.StatusNotFound:
return nil, response.Header, errGiteaNotFound
case response.StatusCode == http.StatusTooManyRequests || response.StatusCode >= 500:
lastErr = newGiteaError(KindStatus, response.StatusCode, "版本记录:Gitea 返回可重试错误", nil)
continue
default:
return nil, response.Header, newGiteaError(KindStatus, response.StatusCode, "版本记录:Gitea 返回错误", nil)
}
}
if lastErr == nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:Gitea 请求失败", nil)
}
return nil, nil, lastErr
}
var errGiteaNotFound = newGiteaError(KindNotFound, http.StatusNotFound, "版本记录:Gitea 上没有该对象", nil)
// ListCommits 读一页提交;同时返回 X-Total-Count(用于完整性对账,不做假 total)。
func (c *GiteaClient) ListCommits(ctx context.Context, page, limit int) ([]RawCommit, int, error) {
if limit <= 0 || limit > giteaDefaultPageSize {
limit = giteaDefaultPageSize
}
query := url.Values{}
query.Set("limit", fmt.Sprintf("%d", limit))
query.Set("page", fmt.Sprintf("%d", page))
query.Set("stat", "false")
query.Set("verification", "false")
body, header, err := c.get(ctx, c.apiURL("/commits", query))
if err != nil {
return nil, 0, err
}
var payload []struct {
SHA string `json:"sha"`
Parents []struct {
SHA string `json:"sha"`
} `json:"parents"`
Created string `json:"created"`
Commit struct {
Message string `json:"message"`
Author struct {
Name string `json:"name"`
Date string `json:"date"`
} `json:"author"`
Committer struct {
Name string `json:"name"`
Date string `json:"date"`
} `json:"committer"`
} `json:"commit"`
}
if err := json.Unmarshal(body, &payload); err != nil {
return nil, 0, newGiteaError(KindParse, 0, "版本记录:提交响应无法解析", err)
}
total := 0
if raw := header.Get("X-Total-Count"); raw != "" {
if _, err := fmt.Sscanf(raw, "%d", &total); err != nil {
total = 0
}
}
commits := make([]RawCommit, 0, len(payload))
for _, item := range payload {
if !fullSHA.MatchString(item.SHA) {
continue
}
parents := make([]string, 0, len(item.Parents))
for _, parent := range item.Parents {
parents = append(parents, parent.SHA)
}
subject, body := splitMessage(item.Commit.Message)
when := parseGiteaTime(item.Commit.Committer.Date)
if when.IsZero() {
when = parseGiteaTime(item.Commit.Author.Date)
}
if when.IsZero() {
when = parseGiteaTime(item.Created)
}
author := item.Commit.Author.Name
if author == "" {
author = item.Commit.Committer.Name
}
commits = append(commits, RawCommit{SHA: item.SHA, Parents: parents, CommittedAt: when,
AuthorDisplay: author, Subject: subject, Body: body})
}
return commits, total, nil
}
// BranchHeadSHA 读分支 HEAD 的完整 SHA(同步记录里的 source_head_sha 用它)。
func (c *GiteaClient) BranchHeadSHA(ctx context.Context, branch string) (string, error) {
if strings.ContainsAny(branch, " /?#") || branch == "" {
return "", newGiteaError(KindParse, 0, "版本记录:分支名非法", nil)
}
body, _, err := c.get(ctx, c.apiURL("/branches/"+branch, url.Values{}))
if err != nil {
return "", err
}
var payload struct {
Commit struct {
ID string `json:"id"`
} `json:"commit"`
}
if err := json.Unmarshal(body, &payload); err != nil {
return "", newGiteaError(KindParse, 0, "版本记录:分支响应无法解析", err)
}
if !fullSHA.MatchString(payload.Commit.ID) {
return "", newGiteaError(KindParse, 0, "版本记录:分支 HEAD 不是完整 SHA", nil)
}
return payload.Commit.ID, nil
}
// ListTags 读全部 tag,并逐个核验它是不是**注释 tag** 以及它指向哪个提交。
// 轻量 tag(object.type == "commit")不会被当作正式版本的证据。
func (c *GiteaClient) ListTags(ctx context.Context) ([]RawTag, error) {
type ref struct {
Ref string `json:"ref"`
Object struct {
Type string `json:"type"`
SHA string `json:"sha"`
} `json:"object"`
}
refs := make([]ref, 0)
for page := 1; page <= 40; page++ {
query := url.Values{}
query.Set("limit", "50")
query.Set("page", fmt.Sprintf("%d", page))
body, _, err := c.get(ctx, c.apiURL("/git/refs/tags", query))
if err != nil {
return nil, err
}
var pageRefs []ref
if err := json.Unmarshal(body, &pageRefs); err != nil {
return nil, newGiteaError(KindParse, 0, "版本记录:tag 列表无法解析", err)
}
refs = append(refs, pageRefs...)
// 短页 = 最后一页(也防住"服务端忽略 page 参数"导致的死循环)
if len(pageRefs) < 50 {
break
}
}
tags := make([]RawTag, 0, len(refs))
for _, item := range refs {
name := strings.TrimPrefix(item.Ref, "refs/tags/")
if name == "" {
continue
}
tag := RawTag{Name: name, TargetSHA: item.Object.SHA}
if item.Object.Type == "tag" {
tag.Annotated = true
tag.TagSHA = item.Object.SHA
// 注释 tag:解引用到真正的提交(tag 对象里的 object.sha)
body, _, err := c.get(ctx, c.apiURL("/git/tags/"+item.Object.SHA, url.Values{}))
if err != nil {
return nil, err
}
var annotated struct {
Object struct {
SHA string `json:"sha"`
} `json:"object"`
}
if err := json.Unmarshal(body, &annotated); err != nil {
return nil, newGiteaError(KindParse, 0, "版本记录:注释 tag 无法解析", err)
}
if !fullSHA.MatchString(annotated.Object.SHA) {
continue
}
tag.TargetSHA = annotated.Object.SHA
}
tags = append(tags, tag)
}
return tags, nil
}
// ReadFile 读某个提交内的文件(用于取该提交的 CHANGELOG.md)。
func (c *GiteaClient) ReadFile(ctx context.Context, sha, path string) (string, error) {
if !fullSHA.MatchString(sha) {
return "", newGiteaError(KindParse, 0, "版本记录:提交必须是完整 40 位 SHA", nil)
}
if strings.Contains(path, "..") || strings.HasPrefix(path, "/") {
return "", newGiteaError(KindParse, 0, "版本记录:文件路径非法", nil)
}
body, _, err := c.get(ctx, c.apiURL("/raw/"+path, url.Values{"ref": []string{sha}}))
if err != nil {
return "", err
}
return string(body), nil
}