企业官网建设流程全解析

• CLI
• 开发工具

本文以pkg/deb/目录下的官方文档（README.md、BUILD.md、CI.md）为骨架，结合仓库中真实的 debian 打包配置、Makefile 与测试脚本源码，系统讲解 chsrc 全平台换源工具在 Debian/Ubuntu 体系下的 deb 包使用全流程。读完本文，你将掌握普通用户安装 deb 包的方法、高级用户手动构建与交叉编译的完整步骤，以及 deb 包自动化构建与发布（CI/CD）的触发机制。

chsrc 是一个用 C 编写的"Change Source everywhere"全平台通用换源工具，能够自动检测并为各种软件源（apt、pip、npm、RubyGems 等）切换到更快的镜像。为了覆盖 Debian 系发行版用户，项目维护了独立的 deb 打包目录 pkg/deb/，既提供现成的二进制包供普通用户下载，也开放了完整的构建规则供高级用户自行打包。本文将从"安装 — 构建 — 验证 — CI 发布 — 底层原理"五个层次展开。

一、deb 包相关文件总览

pkg/deb/目录围绕 deb 包维护了三类文件：CI 配置文件、构建配置与测试脚本。官方 README.md 将其归纳如下：

需要注意的是，镜像仓库中未包含.github/workflows/pkg-deb.yml文件本身，但其构建与发布策略已完整记录在 CI.md 中（见下文"六、CI 自动化构建与发布"）。此外，项目顶层 pkg/README.md 也确认了 deb 是 chsrc 已完成的打包分发渠道之一（- [x] deb）。

二、普通用户安装：两条命令完成

根据 README.md 的说明，普通用户应从项目的 GitHub Releases 页面下载适合自己平台的 deb 包，然后执行：

sudo dpkg -i chsrc_*.deb sudo apt-get install -f # Fix any dependency issues

• 第一条命令dpkg -i完成包的解包与安装，chsrc_*.deb通配符可匹配下载到的具体版本文件名（如chsrc_0.2.3-1_amd64.deb）；
• 第二条命令apt-get install -f用于自动修复可能存在的依赖问题。由于 debian/control 中声明的Depends: ${shlibs:Depends}, ${misc:Depends}会在构建时展开为对libc6等共享库的依赖，在大多数已经装好基础运行库的系统上，dpkg -i通常即可直接成功；但为了稳妥，官方流程仍建议补齐这条依赖修复命令。

安装完成后，chsrc二进制会被放置到/usr/bin/chsrc，并提供chsrc help、chsrc list等子命令。项目顶层 Makefile 的install目标显示，deb 包除二进制外还会安装 man 手册（/usr/share/man/man1/chsrc.1，源文件为 doc/chsrc.1）以及 bash 自动补全脚本（/usr/share/bash-completion/completions/chsrc，源文件为 tool/completion/bash_completion.sh）。

三、debian/ 目录结构详解

deb 包的构建元数据全部位于 pkg/deb/debian/。官方 README.md 给出的目录结构如下：

debian/ ├── changelog # 版本更新日志 ├── compat # debhelper 兼容性版本 ├── control # 包控制信息和依赖 ├── copyright # 版权信息 ├── postinst # 安装后脚本 ├── prerm # 卸载前脚本 └── rules # 构建规则

其中postinst和prerm是带+x执行权限的可执行文件。

对照当前仓库实际内容，目录中共有 6 个文件：changelog、control、copyright、postinst、prerm、rules。README 中列出的compat文件在当前的 debhelper 13 时代已不再需要——这一改动记录在 pkg/deb/Makefile 的注释中："这些本是 debhelper 兼容性版本（debian/compat）为 9 时所需要定义的 targets，然而现在已经为版本 13（debian/compat 已移除），不再需要这些 targets，仅出于实用目的保留。"

各文件的职责如下：

3.1 control：包控制信息与依赖

debian/control 是 dpkg 元数据的核心，分为源包段与二进制包段：

Source: chsrc Section: utils Priority: optional Maintainer: sanchuanhehe <wyihe5520@gmail.com> Build-Depends: debhelper-compat (= 13), build-essential, libc6-dev Standards-Version: 4.6.0 Homepage: https://chsrc.run/ Package: chsrc Architecture: any Depends: ${shlibs:Depends}, ${misc:Depends} Description: Change Source - A tool for changing software sources

• Build-Depends声明构建期依赖：debhelper-compat (= 13)固定 debhelper 兼容级别为 13（这正是debian/compat文件被移除的原因）、build-essential提供编译工具链、libc6-dev提供 C 标准库开发头文件；
• Architecture: any表示该包可以针对任意架构编译，为下文交叉编译提供了合法性基础；
• Depends使用 debhelper 的模板变量${shlibs:Depends}（自动收集二进制链接到的共享库依赖）与${misc:Depends}（收集 debhelper 生成的依赖），构建时由dh_shlibdeps自动展开。

3.2 changelog：版本历史

debian/changelog 遵循 Debian 标准的 changelog 格式，按时间倒序记录：

chsrc (0.2.3-1) unstable; urgency=medium * v0.2.3 已发布 -- 曾奥然 <ccmywish@qq.com> Wed, 29 Oct 2025 11:29:05 +0800

目前已收录0.0.1-1（首个 deb 包）、0.1.9-1、0.2.3-1三个版本。该文件同时也会被安装到系统/usr/share/doc/chsrc/changelog.Debian.gz，用户可随时查阅（见下文 4.4 节）。

3.3 copyright：版权与许可证声明

debian/copyright 采用 Debian 的 machine-readable copyright 格式（SPDX 1.0），按文件划分许可证：

• Files: *：项目主体代码，License 为GPL-3+；
• Files: lib/xy.h：核心头文件 lib/xy.h，License 为MIT；
• Files: pkg/deb/debian/*：本打包目录自身，License 为GPL-3+。

该文件在安装后位于/usr/share/doc/chsrc/copyright，供用户核查许可证义务。

3.4 postinst：安装后脚本

debian/postinst 在包配置阶段（configure）执行三项工作：

1. 更新 man 数据库：mandb -q /usr/share/man/man1/chsrc.1，确保man chsrc立即可用；
2. 确保可执行权限：chmod +x /usr/bin/chsrc；
3. 打印安装提示：提醒用户重启终端以启用自动补全，并建议运行chsrc help开始使用。

脚本对abort-upgrade|abort-remove|abort-deconfigure等中断场景为空处理，并以#DEBHELPER#标记由 debhelper 自动展开维护片段。

3.5 prerm：卸载前脚本

debian/prerm 处理remove|upgrade|deconfigure等卸载场景。由于 chsrc 卸载无需清理特殊系统状态，目前各分支均为空实现（"Nothing special to do during removal"），仅保留 Debian 脚本的标准骨架与#DEBHELPER#占位。

3.6 rules：构建规则（核心）

debian/rules 是 deb 构建的真正驱动者，其工作机制值得展开：

%: dh $@ override_dh_auto_build: @$(MAKE) -C $(Chsrc-Root-Dir) build-in-release-mode override_dh_auto_install: @$(MAKE) -C $(Chsrc-Root-Dir) install DESTDIR=$(CURDIR)/debian/chsrc

• debuild调用dpkg-buildpackage，后者通过fakeroot debian/rules <target>执行本文件；
• 由于通配目标%:的存在，所有任务都会被透传给 debhelper 序列：debian/rules <target>等价于dh <target>，将依次调用dh clean、dh build（此处被override_dh_auto_build覆盖）、dh binary（此处被override_dh_auto_install覆盖）；
• override_dh_auto_build切换到 chsrc 仓库根目录（Chsrc-Root-Dir = $(CURDIR)/../../，即仓库根目录），调用顶层 Makefile 的build-in-release-mode目标编译发布模式二进制；
• override_dh_auto_install以DESTDIR=$(CURDIR)/debian/chsrc调用顶层 Makefile 的install目标，将二进制、man 页、补全脚本安装到临时 staging 目录中，再由dh_install/dh_compress等后续步骤收集成最终.deb。

四、高级用户：手动构建 deb 包

普通用户直接下载 Release 包即可；高级用户可按 BUILD.md 自行构建。

4.1 构建前置依赖

sudo apt-get update sudo apt-get install build-essential debhelper devscripts fakeroot

• build-essential：C 编译工具链（gcc、make 等）；
• debhelper：提供dh系列构建辅助工具（兼容级别 13 由 debian/control 的Build-Depends声明）；
• devscripts：提供debuild封装命令；
• fakeroot：在非 root 环境下模拟 root 权限，使包内文件获得正确的属主与权限。

4.2 一键构建

git clone https://github.com/RubyMetric/chsrc.git cd chsrc # 进入 deb 目录 cd pkg/deb # 执行构建命令 ./Makefile deb-make

注意：./Makefile deb-make实际上是让 make 以该文件作为 Makefile 执行deb-make目标——而由 pkg/deb/Makefile 源码可知，其真正暴露的目标是all（默认目标）、deb-build、deb-prepare、deb-clean，其中deb-build依赖deb-prepare并执行debuild -us -uc -b。因此更规范的写法是：

make -f Makefile # 等价于 make -f Makefile deb-build

debuild -us -uc -b中各参数含义：-us跳过源码签名、-uc跳过 changelog 签名（本地构建无需 GPG）、-b仅构建二进制包。构建产物（.deb、.ddeb、.changes、.buildinfo、.build）会输出到pkg/deb/的上级目录（仓库根目录）中。

4.3 调试构建与产物检查

# 启用详细输出 DEB_BUILD_OPTIONS="nocheck" debuild -us -uc -b # 检查构建日志 less ../chsrc_*.build # 检查包内容 dpkg --contents ../chsrc_*.deb # 或 dpkg-deb --contents ../chsrc_*.deb

• DEB_BUILD_OPTIONS="nocheck"指示 debhelper 跳过测试阶段（若顶层规则在构建中启用了check），适合本地快速迭代；
• dpkg --contents与dpkg-deb --contents等价，均可列出包内文件清单，用于核对二进制、man 页与补全脚本是否如 3.6 节所述正确打包。

4.4 交叉编译

得益于 debian/control 的Architecture: any，可以用dpkg-buildpackage的-a参数为目标架构交叉编译：

# For ARM64 CC=aarch64-linux-gnu-gcc dpkg-buildpackage -us -uc -b -aarm64 # For ARMv7 (armhf) CC=arm-linux-gnueabihf-gcc dpkg-buildpackage -us -uc -b -aarmhf

前提是系统已安装对应的交叉工具链（如gcc-aarch64-linux-gnu、gcc-arm-linux-gnueabihf），并通过CC=...环境变量告知编译系统使用目标架构编译器。

4.5 安装与安装情况验证

sudo dpkg -i ../chsrc_*.deb sudo apt-get install -f # 修复依赖问题 # 运行安装测试脚本 bash ./deb-installation-test.sh # 查看文档安装情况 man chsrc # 查看 deb 包的 copyright cat /usr/share/doc/chsrc/copyright # 查看 deb 包 changelog zless /usr/share/doc/chsrc/changelog.Debian.gz

man chsrc依赖 doc/chsrc.1 这份 troff 格式手册被正确安装并由 postinst 刷新 man 数据库；changelog.Debian.gz来自 debian/changelog，copyright来自 debian/copyright。

4.6 清理构建产物

./Makefile deb-clean

从 pkg/deb/Makefile 源码看，deb-clean会删除 staging 目录debian/chsrc/以及上级目录中所有chsrc_*.deb、chsrc-dbgsym_*.ddeb、chsrc_*.changes、chsrc_*.buildinfo、chsrc_*.build构建产物。

4.7 卸载与完全清除

sudo apt-get remove chsrc

仅删除程序本体；如需连配置文件一起彻底清除：

sudo apt-get purge chsrc

4.8 常见故障排查

BUILD.md 给出的排查要点：

1. 构建失败：检查 debian/control 中的Build-Depends依赖是否完整、版本是否匹配（尤其是 debhelper 兼容级别 13）；
2. 交叉编译失败：确认目标架构的交叉工具链已正确安装，且CC环境变量指向的编译器与-a指定的架构一致；
3. 安装测试失败：检查 postinst 脚本是否有错误——例如mandb不存在或 man 页路径错误都会导致configure阶段异常。

五、安装正确性的自动化验证

pkg/deb/deb-installation-test.sh 是官方提供的"已正确安装"验证脚本（set -e，任一测试失败即退出），共包含 3 组检查：

Test 1 — 二进制存在且可执行：校验/usr/bin/chsrc文件存在且带-x可执行权限（对应 postinst 中的chmod +x /usr/bin/chsrc）。

Test 2 — man 页存在：校验/usr/share/man/man1/chsrc.1是否存在。注意这是WARNING级别而非错误——man 页缺失不会导致测试失败。

Test 3 — 基本功能可用：实际执行/usr/bin/chsrc help与/usr/bin/chsrc list两个子命令，验证二进制在安装环境下能够正常运行（对应 postinst 中"Run 'chsrc help' to get started"的提示）。

全部通过后脚本输出All installation tests of deb package 'chsrc' passed!。这套脚本既可用于本地手工构建后的验证（BUILD.md 中bash ./deb-installation-test.sh），也可作为 CI 发布前把关的最后一道工序。

六、CI 自动化构建与发布

CI.md 记录了 deb 包从构建到发布的完整 CI/CD 策略。

6.1 支持的架构与构建产物

• 当前 CI 支持amd64（x86_64）架构的构建；
• 每次 CI 构建产生两类产物：
  1. deb 包文件：chsrc_<version>-1_<arch>.deb（命名与 debian/changelog 中的版本号对应，如chsrc_0.2.3-1_amd64.deb）；
  2. APT 仓库元数据：Packages与Packages.gz，用于将产物组织成可供 apt 直接消费的软件源。

6.2 自动触发时机

CI 在三种情况下自动运行：

1. Push 事件：当代码 push 到gh-build分支时自动构建，并将 deb 包上传到名为pre的特定 release 中（可理解为预发布通道）；
2. Release 事件：当创建新的 release 时自动构建，并将 deb 包上传到最新的这个 release 中（正式发布通道）；
3. 手动触发：可在 GitHub Actions 页面手动触发构建，用于按需验证。

6.3 手动发布流程

官方建议的发布步骤：

1. 确保所有代码已合并到主分支；
2. 更新版本号和 debian/changelog（版本号需要与 git tag 保持一致）；
3. 创建并推送 git tag：git tag v1.2.3 && git push origin v1.2.3；
4. 在 GitHub 上创建 release（触发 6.2 中的 Release 事件）；
5. CI 将自动构建并上传 deb 包。

七、从源码理解打包链路

将各文档串联起来，chsrc 的 deb 打包完整链路是：

debuild -us -uc -b └─ dpkg-buildpackage └─ fakeroot debian/rules <target> └─ dh <target> ├─ override_dh_auto_build → make -C <仓库根> build-in-release-mode # 顶层 Makefile 编译发布版 └─ override_dh_auto_install → make -C <仓库根> install DESTDIR=debian/chsrc # 安装到 staging └─ 顶层 install 目标： install -D -m 755 <release二进制> /usr/bin/chsrc install -D -m 644 doc/chsrc.1 /usr/share/man/man1/chsrc.1 install -D -m 644 tool/completion/bash_completion.sh /usr/share/bash-completion/completions/chsrc

• 顶层 Makefile 的build-in-release-mode目标使用发布优化参数（CFLAGS_optimization）编译，与开发模式区分；
• 顶层 Makefile 的install目标通过DESTDIR前缀完成重定位安装，这正是 debhelper staging 目录机制能够工作的前提；
• pkg/deb/debian/rules 通过$(CURDIR)/../../回到仓库根目录，因此构建必须在pkg/deb目录下进行（pkg/deb/Makefile 注释也强调了这一约束）。

理解这条链路后，无论是排查构建失败、扩展新架构（如arm64），还是定制安装内容，都能精准定位到对应的 Makefile 目标与 debian 配置文件的改动位置。

小结

chsrc 的 deb 包体系是一条完整、自洽的工程链路：面向普通用户提供"下载即装"的二进制体验（dpkg -i两条命令），面向高级用户开放可复现的手工构建流程（依赖声明、一键构建、交叉编译、产物检查、卸载清理），面向维护者提供自动化发布通道（gh-build分支、Release 事件与手动触发三类入口）。核心配置集中在 pkg/deb/debian/ 的 6 个文件中，构建入口是 pkg/deb/Makefile 与顶层 Makefile，安装正确性由 deb-installation-test.sh 把关，三者共同保证了 Debian/Ubuntu 用户能够以最标准的方式获得 chsrc 的换源能力。

• CLI
• 开发工具