# 13太保玩转github-第10太保-李存贤-发布门户

> Release、Pages、Wiki 三件事，决定成果能不能稳稳交出去。

```text
[读者] 已经在用 GitHub 做项目，但发布还靠手写说明的维护者
[痛点] 版本、文档、入口散在 README、聊天记录和 issue 里
[现在读] 项目有了教程 tag 和软件版本，需要稳定交付门户
[读完] 能独立配置 Release 分类、Pages 发布和自定义域验证
```

```text
[旧方案] README 堆全部说明 + 手工写 release notes
    |
    v
[新需求] 版本可追踪、文档有门户、协作有边界
    |
    v
[冲突] README 不擅长版本，Release 不做导航，Wiki 不可控
    |
    v
[后果] 用户找不到入口，维护者无法复现交付
```

我是老李，在深圳带团队做 Java 与 AI 工程化落地，见过太多“功能能跑，但没人知道怎么发”的项目。

springaialibabapractice 已经积累到十八章，教程 tag 是 ch01 到 ch18，软件版本又要走 SemVer，两条线混在一起，发布入口越来越乱。

李存贤在《旧五代史》里被称“忠谨周慎”，守城任事都很稳。发布门户要的就是这种稳：不炫技，但每一步都能验证、能回滚。

当代码已经能跑，为什么用户还是不知道版本是什么、怎么用、文档在哪？

是把 README 不断堆长，还是用 Release 管版本、Pages 管门户、Wiki 管协作？

如果继续把发布说明留在聊天记录里，三个月后谁来复现这次交付？

# 01、故事

项目走到第10章，前面九章已经把仓库协作、Actions、安全、Projects、Discussions 等能力搭起来。可交付时还是乱：读者问“v0.1.0 和 ch10 是什么关系”，维护者问“这次 release 包含哪些 PR”，新人问“文档从哪里开始看”。

当前方案是继续往 README 堆内容，release notes 手写，Pages 没开。变化是课程进入软件版本发布阶段，教程 tag 和软件 SemVer 必须分离。冲突是 README 无法表达版本状态，手写 notes 无法稳定分类，没有 Pages 就没有稳定门户。

任务是：用 GitHub Releases、Pages 和 Wiki/README 分工，把 springaialibabapractice 的发布门户做成可验证配置，而不是一次性说明。

> 守城先守门
> 交付先交版本
> 入口越少越稳
> 证据越多越准

# 02、问题

旧方案失效：README 越堆越长，Release 手写，Pages 缺失。

业务影响：用户不知道最新版本、怎么用、文档在哪；维护者无法复现交付。

技术表现：ch 标签和 v 标签混用；release notes 没有分类；自定义域没有验证。

可验证完成标准：

- `.github/release.yml` 在默认分支，Release 按“新增/修复/文档/依赖”分类。
- `gh release create --verify-tag --generate-notes` 成功。
- Pages 用官方 Actions 发布，首页全中文，含 Quick Start/十八掌路线/FAQ/贡献入口。
- 真实仓库验证命令输出记录到 `docs/github-ops/10-release-pages.md`。

> 旧法堆文档
> 新求可追踪
> 乱在无边界
> 痛在难复现

# 03、原理

Releases 是 tag 的语义包装：tag 指向 commit，release 提供说明、附件和下载入口。GitHub 官方关于 releases 的文档在这里：https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases。关键判断：release 不是代码本体，而是交付契约。

自动生成 release notes 依赖 PR label 和 `.github/release.yml`。官方说明在：https://docs.github.com/en/enterprise-cloud@latest/repositories/releasing-projects-on-github/automatically-generated-release-notes。反直觉判断：自动生成 release notes 不是省去写文档，而是把文档成本前移到 PR 标签治理。

Pages 是静态站点发布通道。README 是仓库门面，Wiki 是协作草稿，Pages 是稳定门户。自定义域要先在 GitHub 配置并验证，再改 DNS。官方说明：https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site。反直觉判断：先改 DNS 再配 GitHub 看似快，实际把域名接管风险和证书失败风险引入。

教程 tag ch01...ch18 与软件 SemVer v0.x.y/v1.x.y 必须分离。ch 标签是课程路线，v 标签是软件交付。两套契约不能混。

> 发布非发码
> 契约在版本
> 标签先治理
> 域名后接管

# 04、架构

```text
[输入] tag/PR/commit
    |
    v
[模块] Release + Pages + Wiki/README
    |
    v
[数据/状态] tag、release notes、CNAME/HTTPS、站点构建产物
    |
    v
[处理] 生成 notes、Actions 构建部署、DNS/证书
    |
    v
[输出] 版本页、文档门户、协作入口
```

边界：Release 不负责导航，Pages 不负责协作，Wiki 不负责版本。收益：入口稳定，证据可查。代价：标签治理和 DNS 等待。适用条件：多版本、多入口、需要对外交付的项目。

> 输入是标签
> 模块各守位
> 状态需可验
> 输出要可追

# 05、实战一次

环境/版本：

- GitHub.com 仓库 springaialibabapractice，默认分支 main。
- git 2.x，gh CLI 2.x（以本机 `gh --version` 为准）。
- 仓库写权限，Actions 可用，Pages 可用。

依赖：无额外运行时，Pages 使用官方 Actions。

配置：`.github/release.yml`

```yaml
changelog:
  exclude:
    labels:
      - skip-changelog
  categories:
    - title: 新增
      labels:
        - feature
        - enhancement
    - title: 修复
      labels:
        - bug
        - fix
    - title: 文档
      labels:
        - docs
        - documentation
    - title: 依赖
      labels:
        - dependencies
        - dependabot
    - title: 其他
      labels:
        - '*'
```

Pages workflow：`.github/workflows/deploy-pages.yml`

```yaml
name: Deploy Pages
on:
  push:
    branches:
      - main
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/site
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
```

Pages 首页：`docs/site/index.html`

```html
<!doctype html>
<html lang='zh-CN'>
<head>
  <meta charset='utf-8'>
  <title>springaialibabapractice 发布门户</title>
</head>
<body>
  <h1>springaialibabapractice 发布门户</h1>
  <h2>Quick Start</h2>
  <p>从 v0.1.0 开始，按 Releases 页面选择版本。</p>
  <h2>十八掌路线</h2>
  <p>教程标签 ch01 到 ch18 对应课程章节，与软件 SemVer 分离。</p>
  <h2>FAQ</h2>
  <p>版本看 Releases，协作草稿看 Wiki，稳定文档看本页。</p>
  <h2>贡献入口</h2>
  <p>提交 PR 时请打上 feature、bug、docs 或 dependencies 标签。</p>
</body>
</html>
```

启动：

```bash
git checkout -b githubops/10-release-pages
git add .github/release.yml .github/workflows/deploy-pages.yml docs/site/index.html
git commit -m 'docs(gh10): establish release and pages workflow'
git push -u origin githubops/10-release-pages
```

创建 tag 和 release：

```bash
git tag -a v0.1.0 -m 'release v0.1.0'
git push origin v0.1.0
gh release create v0.1.0 --verify-tag --generate-notes --title 'v0.1.0'
gh release view v0.1.0
```

请求验证：

```bash
gh release view v0.1.0 --json tagName,isDraft,url
gh run list --workflow=deploy-pages.yml --limit 3
curl -I https://<username>.github.io/springaialibabapractice/
```

示例输出：

```console
tagName: v0.1.0
isDraft: false
url: https://github.com/<owner>/springaialibabapractice/releases/tag/v0.1.0
```

未在当前环境实测，以下为预期结果。把命令输出记录到 `docs/github-ops/10-release-pages.md`。

Web SaaS 操作：

- Releases → Draft a new release：选择 tag、target、title，点击 Generate release notes。
- Settings → Pages：Source 选 GitHub Actions；Custom domain 填 `docs.example.com`；DNS 验证后勾选 Enforce HTTPS。
- Wiki/README/Pages 分工：README 门面，Wiki 协作，Pages 门户。

> 先建真标签
> 再跑自动化
> 请求看响应
> 验证留证据

# 06、排查

诊断链1：Release notes 未按分类展示。

现象：自动生成只有默认分组。

怀疑：`.github/release.yml` 未生效或 label 不匹配。

检查：`gh api repos/<owner>/springaialibabapractice/contents/.github/release.yml`；`gh pr view <n> --json labels`。

证据：文件在非默认分支，或 PR 没有 feature/bug/docs/dependencies 标签。

根因：标签治理缺失，文件未合并到默认分支。

修复：把 release.yml 合并到默认分支，补 label，在 Web 编辑 release 点击 Generate release notes；或删除 release 保留 tag 后重建。

诊断链2：Pages 自定义域 HTTPS 一直 pending。

现象：Enforce HTTPS 灰色，证书未签发。

怀疑：DNS 未生效或 CNAME 冲突。

检查：`dig +short docs.example.com`；`gh api repos/<owner>/springaialibabapractice/pages`。

证据：DNS 返回旧 IP，或存在 A/CNAME 冲突，或 Cloudflare 代理开启。

根因：先改 DNS 后配 GitHub，或域名未验证。

修复：先在账户 Settings → Pages → Add a domain 加 TXT 验证；再在仓库 Pages 设置保存 custom domain；然后配置 DNS CNAME 到 `<owner>.github.io`；关闭代理；等待签发后勾选 Enforce HTTPS。

**错误尝试：** 直接执行 `gh release create v0.1.0 --generate-notes`，不先建 tag、不加 `--verify-tag`。结果 tag 从默认分支当前 commit 创建，可能指向错误位置。为什么错误：没有先确认 tag 指向发布 commit，发布契约就被写错。

> 现象先记录
> 怀疑再检查
> 证据定根因
> 修复可回滚

# 07、优化

根因：标签治理缺失、发布前没有 tag 校验、自定义域顺序错误。

修改：

- 在发布前增加显式 tag 校验。
- 统一 PR 标签，要求 feature/bug/docs/dependencies。
- 自定义域先验证 TXT，再配仓库 custom domain，最后改 DNS。

原因：让发布门户依赖可验证状态。

新行为：

```bash
git rev-parse v0.1.0^{commit}
gh release create v0.1.0 --verify-tag --generate-notes --title 'v0.1.0'
```

`--verify-tag` 在 tag 不存在时失败，阻止错误发布。

验证：`gh release view v0.1.0 --json tagName,isDraft,url`；`gh run list --workflow=deploy-pages.yml`；`curl -I`。示例输出标注。

> 根因改流程
> 校验前置跑
> 新行为可证
> 旧问题收口

# 08、演进

```text
[同一输入]
    |
    +--[V1] 手工 release notes + README 堆文档 / 代价：分类混乱、入口分散
    |
    +--[V2] release.yml + Pages Actions + 域名验证 / 代价：标签治理成本、DNS 等待
    |
[Trade-off]
得到：可复现的发布门户；失去：纯手工自由度；适用：多版本、多入口项目
```

正确性：V2 先验证 tag，Release 指向明确 commit。稳定性：V2 标签分类，notes 可重复生成。复杂度：V2 增加标签治理和 DNS 验证步骤。成本：V2 多花几分钟前置检查，减少错误发布。适用范围：多版本、多入口、需要对外文档的项目。遗留问题：Wiki 协作规范、Pages 版本选择器、域名续期。

> 同一份输入
> 两版不同路
> 取舍在边界
> 演进看代价

# 09、洞见

## 9.1 发布门户不是文档站，是承诺边界

Release 承诺版本，Pages 承诺入口，Wiki 承诺协作范围。三者混在一起，用户就不知道哪个是正式答案。

反直觉判断：发布门户的核心不是“写更多文档”，而是“减少入口”。

## 9.2 自动生成 notes 的瓶颈在标签治理

`.github/release.yml` 只是分类器，真正的输入是 PR label。没有标签，自动生成只能给出默认分组。

反直觉判断：自动生成 release notes 不是省去写文档，而是把文档成本前移到 PR 标签。

## 9.3 自定义域的顺序决定安全

先改 DNS 再配 GitHub，可能被他人接管或证书失败。先验证 TXT，再配仓库，最后改 DNS，风险更低。

反直觉判断：先改 DNS 看似快，实际把接管风险和证书失败风险引入。

## 9.4 教程 tag 与软件 SemVer 必须分离

ch01...ch18 是课程路线，v0.x.y/v1.x.y 是软件交付。同一个仓库里，tag 不是一套命名规则，而是两套交付契约。

反直觉判断：tag 越多越乱，不是因为数量，而是因为契约没有分层。

> 门户非文档
> 承诺有边界
> 标签定质量
> 顺序定安全

# 10、系统落地

原来有什么：README、章节分支、教程 tag、若干 Actions。

本篇新增：`.github/release.yml`、Pages workflow、`docs/site/index.html`、Release 模板、`docs/github-ops/10-release-pages.md`。

现在能做什么：用 `gh release create --verify-tag --generate-notes` 发布软件版本；Release 按标签分类；Pages 提供全中文门户。

还缺什么：域名 TXT 验证记录、版本选择器、Wiki 协作规范、发布 checklist 自动化。

下一步：把 Pages 门户接入版本化文档，Wiki 只保留协作草稿。

> 原来散入口
> 现在有门户
> 还缺自动化
> 下一步收口

# 11、小结

```text
Q1 → Release 管版本契约，Pages 管稳定门户，Wiki 管协作
Q2 → 用 release.yml + Actions Pages + 域名验证，而不是堆 README
Q3 → 先验证 tag 和域名，再发布，避免错误 tag 和接管风险
状态 → 发布门户可复现，Release 分类生成，Pages 可访问
```

> 问题有答案
> 状态可交付
> 能力可复现
> 边界已划清

# 12、作业

## 12.1 理解题：为什么 Release 不是代码本体？

参考答案：tag 指向 commit，release 是 tag 的说明、附件和入口。代码本体在 commit 和 tag，release 负责交付契约。

## 12.2 实战题：用 gh CLI 创建一个带自动分类 notes 的 release。

参考答案：先创建并推送 tag，再执行 `gh release create v0.1.0 --verify-tag --generate-notes --title 'v0.1.0'`，最后用 `gh release view v0.1.0` 验证。

## 12.3 排障题：自动生成 notes 没有分类，先查什么？

参考答案：先确认 `.github/release.yml` 在默认分支，再查 PR label 是否匹配 categories，最后确认 release notes 生成时使用的 PR 范围。

## 12.4 架构判断题：自定义域为什么要先 GitHub 验证再改 DNS？

参考答案：先验证所有权，能降低域名被他人接管的风险；先配仓库 custom domain 再改 DNS，能让 GitHub 的 DNS check 和证书签发按预期进行。

> 理解验概念
> 实战验命令
> 排障验证据
> 架构验取舍

# 13、思考

发布门户的冲突从来不是“有没有文档”，而是“用户能不能找到唯一可信的版本、入口和协作边界”。李存贤的“忠谨周慎”落在工程上，就是先验证 tag，再验证域名，最后才对外交付。能复现的发布，才算真正交付。

> 一念辨边界
> 一证定根因
> 一改知取舍
> 一役见真章

我是老李，在深圳带团队做 Java 与 AI 工程化落地，见过太多“功能能跑，但没人知道怎么发”的项目。

13太保玩转github-第10太保-李存贤-发布门户

用李存贤“忠谨周慎”的交付观，把 GitHub Release、Pages、Wiki 组织成可验证的发布门户，并落到 springaialibabapracti

架构师

开发工具

运维

职业发展

从README堆砌转向GitHub Release管版本、Pages建门户、Wiki做协作的三层架构，通过release.yml自动分类PR标签，用Actions部署全中文文档站点，并严格按先验证TXT再改DNS的顺序配置自定义域。确保发布可复现，入口稳定，教程tag与软件SemVer分离。

代码解释

GitHub

Java

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

13太保玩转github-第10太保-李存贤-发布门户-腾讯云开发者社区-腾讯云

13太保玩转github-第10太保-李存贤-发布门户

13太保玩转github-第10太保-李存贤-发布门户

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐