1. 先把源这件事说透apt 与 sources.list 到底在干什么很多人第一次碰 Ubuntu 的 apt 源配置都是被逼的。要么是apt update卡在Connecting to archive.ubuntu.com转到天荒地老要么是装个nvidia-driver-535卡在下载 500MB 的包上进度条十分钟不动一格。改完源之后速度从几十 KB/s 跳到十几 MB/s那种感觉跟换了台机器一样。但真正把源配置搞明白的人不多大部分人是从网上抄一段现成的配置粘进去能跑就不管了。问题是 Ubuntu 从 24.04 开始主推 deb822 新格式抄来的老格式配置放进去要么不生效要么和新文件打架apt update直接报重复定义。所以我打算从一次 apt install 到底发生了什么讲起把每个配置项拆开揉碎最后落到能直接抄的实操步骤上。这篇内容适合三类人刚装完 Ubuntu 想换源但不知道每个字段什么意思的新手、维护内网几十台机器需要统一源配置的运维、以及遇到 GPG 报错或 404 之后只能靠重装系统解决的老用户。我会尽量用生活化的类比解释机制同时在关键的地方给出准确的字段语义和可复现的命令读完你应该能做到看一行源配置就知道它指向哪个仓库、包含哪些组件、用哪把密钥校验而不是只会复制粘贴。1.1 一次 apt install 背后发生的完整链路先建立一个心智模型。你把apt想象成一个采购员/etc/apt/sources.list和/etc/apt/sources.list.d/里的文件就是它的供应商名录而/var/lib/apt/lists/是它手上的库存清单。当你敲下sudo apt install nginx时真正发生的事情分几步走。第一步apt 读取所有源配置文件把每个仓库的地址、发行版代号、组件列表拼成实际的 URL。第二步它去每个仓库下载Packages索引文件——这个文件是纯文本的里面记录了每个包的名称、版本、依赖关系、文件大小和 SHA256 校验值但不含包体本身。第三步把这些索引解压后存到/var/lib/apt/lists/。第四步apt 在本地索引里做依赖求解算出装 nginx 需要哪几个包。第五步按依赖顺序从仓库拉取.deb包体下载到/var/cache/apt/archives/。第六步用dpkg逐个解包安装。理解这个链路的好处是你会知道apt update和apt upgrade是两件完全不同的事。前者只刷新索引清单后者才真正动包。所以磁盘空间紧张的时候/var/lib/apt/lists/占几百 MB 是正常的它不是缓存垃圾删了下次 update 还得重新下。而/var/cache/apt/archives/里的.deb才是可以放心清的这也是apt clean干的事情。还有一个细节值得说apt update是按源逐个请求的任何一个超时都会拖慢整体速度默认超时相对宽松。所以当你的源列表里有几个不可达的条目时整个 update 会显得特别慢而不是干脆失败。这也是为什么排查 apt 慢的第一步永远是看有没有失效的源。1.2 软件源、仓库、组件与架构之间的关系这里有几个词经常被混用理清楚之后看配置就不迷糊了。软件源repository / mirror指的是一个 HTTP 或 FTP 站点比如官方的archive.ubuntu.com或者各高校和企业提供的镜像站点。镜像站做的事很简单定期从上游同步一份完整拷贝让地理位置近的用户就近下载。所以你在镜像站上看到的内容和官方是一模一样的只是域名不同。发行版代号suite / codename是 Ubuntu 的版本代号比如 20.04 是focal22.04 是jammy24.04 是noble。每个代号下面还会派生几个口袋noble是发布时的冻结快照noble-updates是发布后的常规更新noble-security是安全补丁noble-backports是从新版本回迁的软件noble-proposed是待验证的预发布更新。新手最容易犯的错是把这几种混在一个组件列表里或者漏掉 security 导致系统长期不打安全补丁。组件component是 Ubuntu 对软件包做的分类一共四个main是官方支持的自由软件restricted是官方支持的专有驱动显卡驱动就在这里universe是社区维护的自由软件multiverse是有版权或法律限制的软件。默认的四组件全开是有道理的——你装nvidia-driver-535需要restricted装很多开发工具需要universe。架构architecture则是 CPU 类型现在绝大多数是amd64ARM 服务器是arm64树莓派早期是armhf。只有你需要在一台机器上装另一种架构的包比如给 ARM 设备做交叉编译准备时才需要在源配置里显式声明架构否则 apt 会自动按当前系统架构去请求。把这四个维度想成快递地址 课本版本 章节范围 语言版本源配置那一行字符串的含义就清楚了。1.3 为什么国内机器必须换源这不是玄学。官方源archive.ubuntu.com的服务器在境外物理距离带来的延迟是客观存在的几十毫秒到几百毫秒不等。更关键的是单个连接的带宽会被限制而且跨国链路在晚高峰时抖动明显表现为下载速度忽高忽低甚至断流。换到地理位置近的镜像站好处不只是快。镜像站通常有更大的出口带宽apt update时并发拉取索引的体验明显更顺同时因为链路短出现连接超时的概率低很多。实测下来同样是noble的完整组件索引换源前后 update 耗时的差距常常在五到十倍之间。注意换源本身不改变任何软件内容镜像站只是搬运工。但镜像站有同步延迟通常几小时以内所以极个别情况下你需要的包版本在镜像站上还没同步过来。这种时候临时切回官方源即可不必怀疑是配置写错了。2. sources.list 配置项逐字段拆解搞清楚机制之后就可以正面拆那行看似天书的配置了。老格式也叫 one-line style长这样deb http://archive.ubuntu.com/ubuntu/ noble main restricted universe multiverse这一行只有五个字段但每个字段都有讲究。我按顺序把它们讲透。2.1 单行格式的五个字段顺序不能错第一个字段是归档类型只有两个合法值deb表示这个源提供二进制包编译好的.debdeb-src表示提供源码包Sources索引加.dsc/.tar.xz等。日常使用只需要deb。第二个字段是仓库基地址注意结尾的斜杠。这个斜杠不是可有可无的装饰apt 会把后面的路径直接拼上去比如最终请求的是http://archive.ubuntu.com/ubuntu/dists/noble/main/binary-amd64/Packages.xz。少写斜杠有时候也能跑但不同版本的 apt 行为不完全一致建议严格保留。第三个字段是发行版代号可以是noble也可以是noble-updates、noble-backports这类派生名。一个容易忽略的点是同一个代号下可以并列写多个用空格分隔apt 会把多个口袋的索引合并看。但更清晰的做法是每个口袋写一行报错时能一眼定位是哪个源出的问题。第四个及之后的所有字段都是组件列表顺序无所谓重复也没关系。main restricted universe multiverse四件套是官方推荐的完整组合。第五个位置其实没有第五个字段了组件一直写到行尾。如果你看到有人在组件后面又写了东西那多半是写错了。2.2 deb 和 deb-src 到底什么时候才需要很多教程会让你把deb-src也一起加上理由是以后可能要编译源码。我的建议是除非你明确要做 Debian 打包、内核编译或者需要apt source拉某个包的源码否则不要加。原因是deb-src会让apt update额外下载每个组件的Sources索引体积和耗时都不小而且这些索引 99% 的时间是躺在那里吃磁盘。Ubuntu 官方从某个版本开始默认就注释掉了deb-src行就是这个思路。需要的时候再临时打开改完跑一次apt update用完注释掉这是更务实的做法。注意源码包通常在universe和main里都有做打包工作的话四个组件的 src 都要开。2.3 发行版代号写错会发生什么代号写错是新手最常踩的坑而且报错信息很有迷惑性。如果你在 22.04jammy上写了focalapt update会正常完成——因为focal确实是个合法的目录仓库里真有这些文件。但接下来你装包时会发现版本对不上或者装了个老版本的库把系统依赖搞乱。更糟的是把代号写成stable或testing这类 Debian 风格的别名。Ubuntu 仓库里也有stable这个目录但它指向的东西和你想的完全不是一回事可能会拉进一堆不匹配的包。确认自己代号的方法lsb_release -cs # 或者 . /etc/os-release echo $VERSION_CODENAME第二个命令更可靠因为lsb_release在某些精简系统上没装。拿到代号之后照着写一个字母都别改。2.4 方括号里的选项字段arch、signed-by、lang在deb和 URL 之间还可以插入一个方括号包裹的选项块多个选项用空格分隔。这块是很多人看到但从来没搞懂的部分。[archamd64]用于限制这个源只对指定架构生效。典型场景是你在 x86 上通过dpkg --add-architecture arm64加了 ARM 架构支持但只想让某个特定源提供 ARM 包其他源保持 amd64这时候就需要按源声明 arch否则 apt 会去找所有源的 arm64 索引找不到就是一堆 404。[signed-by/usr/share/keyrings/xxx.gpg]指定这个源用哪把 GPG 公钥校验签名。这是第三方源的标准姿势后面讲 PPA 和 Docker 源时会重点说。它的作用是防止公钥全局信任带来的风险——以前的做法是把密钥apt-key add进全局信任环意味着任何源都能用这把密钥签名安全性差。[langzh_CN]这种是针对Translation索引的控制下载哪些语言的翻译文件。默认情况下 apt 会下载所有语言的翻译索引中文用户可以把语言限制到zh_CN和en能省下不少 update 时间和流量。这个选项不常用但仓库大的时候效果明显。# 只下载中英文翻译索引的写法 deb [langzh_CN,en] http://mirrors.example.edu.cn/ubuntu/ noble main restricted universe multiverse还有一个[trustedyes]字面意思是跳过签名校验。这玩意儿只应该在完全可控的内网离线源上使用公网源用它是自找麻烦。我见过有人为了解决 GPG 报错直接加trustedyes等于把整条供应链的校验环节拆掉了。3. deb822 新格式Ubuntu 24.04 之后绕不开的写法如果你装的是 Ubuntu 24.04 或更新版本打开/etc/apt/sources.list大概率会发现里面只有一行注释写着这个文件已经被/etc/apt/sources.list.d/ubuntu.sources取代。这不是 bug是 apt 2.4 之后引入的 deb822 格式成为默认。3.1 .sources 文件的结构与字段含义新格式长这样Types: deb URIs: http://archive.ubuntu.com/ubuntu/ Suites: noble noble-updates noble-backports Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg对比老格式字段名的映射关系是deb对应TypesURL 对应URIs代号对应Suites组件对应Components。新增了Signed-By作为必填项这是最大的变化——官方源现在也显式声明用哪把密钥了。字段名不区分大小写Types和types都行但社区惯例是首字母大写。值里的多个条目用空格分隔这点和老格式一致。缩进无关紧要但同一段落内不能有空行空行意味着一个新的源块开始。一个.sources文件里可以写多个块用空行分隔。这就是为什么新版把三个口袋塞进一个块里写Suites: noble noble-updates noble-backports而不是像老格式那样写三行。简洁是简洁了但出问题时定位稍微麻烦一点因为一个块里的任何一项出错都会让整个块失效。3.2 Signed-By 与密钥路径的正确姿势Signed-By的值可以是一个文件路径也可以直接内嵌公钥内容还可以是多个路径用空格分隔。实践中都是写路径。这里有个容易搞混的点Ubuntu 系统自带的密钥在/usr/share/keyrings/下比如ubuntu-archive-keyring.gpg管官方源ubuntu-pro-*-keyring.gpg管 Pro 相关服务。而你自己用curl下载的第三方公钥惯例是放到/etc/apt/keyrings/目录下并且要用gpg --dearmor转成二进制格式因为直接下载的往往是 ASCII armor 格式文本可见的-----BEGIN PGP PUBLIC KEY BLOCK-----apt 要的是.gpg二进制。sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://example.com/repo-key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/example-archive-keyring.gpg sudo chmod ar /etc/apt/keyrings/example-archive-keyring.gpgchmod ar这一步经常被忽略但很关键——apt 以_apt用户身份做下载校验如果文件权限是 600 只有 root 能读apt 会报权限错误而报错信息通常只说无法读取密钥不会告诉你具体是权限问题。3.3 两种格式的共存规则与迁移方法apt 同时支持两种格式扫描顺序是/etc/apt/sources.list里的老格式行、/etc/apt/sources.list.d/下的.list文件、以及.sources文件。它们不是互斥的可以共存。但这里有个大坑如果同一个仓库同时出现在老格式和新格式里apt 不会去重而是会把索引下载两遍apt update输出里你能看到重复的Get行。更严重的情况是版本冲突比如两个块声明了同一组件的不同 URLapt 会优先使用列出来的第一个匹配仓库但下载索引时两个都下浪费时间还可能触发哈希校验困惑。迁移的建议是二选一不要混着来。新装 24.04 及以上就用.sources把/etc/apt/sources.list里剩余的有效行全部注释掉实体文件放在/etc/apt/sources.list.d/下一个来源一个文件文件名用有意义的名字比如ubuntu.sources、docker.sources、nodesource.sources。这样以后要禁用某个源直接重命名加.disabled后缀就行比在长文件里注释行干净得多。4. 动手实操从备份到验证的完整流程理论讲完来一遍完整操作。我按 Ubuntu 24.04 的环境走22.04 和 20.04 的同学把代号换成jammy/focal其余步骤类似。4.1 备份与代号确认永远先备份。改坏了还能回滚这是唯一能让你放心折腾的保障。sudo cp -a /etc/apt/sources.list /etc/apt/sources.list.bak.$(date %F) sudo cp -a /etc/apt/sources.list.d /etc/apt/sources.list.d.bak.$(date %F)cp -a保留权限和时间戳比cp -r更适合备份系统文件。日期后缀方便你以后有多份备份时区分。然后确认代号和架构. /etc/os-release echo 代号: $VERSION_CODENAME dpkg --print-architecture输出应该是noble和amd64或你的实际平台。4.2 写一份可用的源配置以 Ubuntu 24.04 为例创建/etc/apt/sources.list.d/ubuntu.sourcesTypes: deb URIs: http://mirrors.example.edu.cn/ubuntu/ Suites: noble noble-updates noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg把mirrors.example.edu.cn替换成你实际要用的镜像站域名。选择镜像站有几个考量一是看它是否同步了你要用的代号老版本系统尤其要确认镜像站还保留着旧代号的目录二是看它的更新频率公告里会写同步周期三是看你所在网络到它的链路质量这个只能实测。同时把老文件清干净避免重复sudo sed -i s/^deb /#deb / /etc/apt/sources.list或者干脆清空内容只留一行注释说明去哪看配置。我个人习惯是清空文件内容加一行注释指向新文件这样以后别人接手也看得懂。4.3 更新缓存并验证生效sudo rm -rf /var/lib/apt/lists/* sudo apt update先删索引再 update是为了避免残留的旧索引干扰判断。命令输出里每个Get行都会显示实际请求的 URL 和下载速度确认域名是你配置的镜像站速度相比之前有明显提升就说明生效了。如果输出里还有archive.ubuntu.com的请求说明某个地方还留着生效的官方源回去用grep -r archive.ubuntu.com /etc/apt/找出来。最后做一个实际安装验证sudo apt install -y --reinstall htop--reinstall对它已经装过的包也能跑借它验证下载链路通畅。装完之后可以看看下载速度apt-get download tree ls -lh tree_*.deb rm tree_*.deb4.4 第三方源的添加规范拿 Docker 官方源举例因为它的写法很典型sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg然后写/etc/apt/sources.list.d/docker.sourcesTypes: deb URIs: https://download.docker.com/linux/ubuntu Suites: noble Components: stable Architectures: amd64 Signed-By: /etc/apt/keyrings/docker.gpg注意这里Signed-By指向的是你自己下载的密钥而Architectures限定了只对 amd64 生效。第三方源通常只提供部分架构声明清楚能避免一堆 404。PPA 的处理方式稍有不同它走的是add-apt-repository命令底层会帮你下载密钥并生成配置文件。PPA 在 24.04 上生成的也是 deb822 格式。用 PPA 的前提是你已经装了software-properties-common这是个常见的依赖缺失点。提示每加一个第三方源之前先想清楚为什么需要它。系统自带仓库里的包优先用系统仓库的第三方源越少依赖冲突和更新失败的概率越低。我维护的机器上第三方源通常不超过三个。5. 那些年踩过的坑常见报错与排查配置改多了报错就一定遇到。这一节把高频问题整理清楚。5.1 NO_PUBKEY 与 GPG 签名校验失败报错长这样W: GPG error: https://example.com/repo stable InRelease: The following signatures couldnt be verified because the public key is not available: NO_PUBKEY ABCD1234EF567890含义很直白仓库的InRelease文件带签名但 apt 手里没有对应的公钥没法验证。解决就是把公钥装上。# 从密钥服务器拉取需要能访问 keyserver sudo gpg --keyserver keyserver.ubuntu.com --recv-keys ABCD1234EF567890 sudo gpg --export ABCD1234EF567890 | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg # 或者从仓库站点直接下载 .asc 文件 curl -fsSL https://example.com/repo/key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/example.gpg然后在源的Signed-By里指向这个文件。顺序很重要先装密钥再 update否则还是报错。另一个相关报错是EXPKEYSIG或KEYEXPIRED意思是公钥过期了。同样是重新拉取但注意某些仓库换了密钥需要先删旧密钥否则新旧两份都在会导致签名匹配混乱。5.2 404 Not Found 与 Hash Sum mismatch404通常意味着 URL 拼出来指向了不存在的文件原因无非几种代号写错了比如把noble写成了nobles、组件名拼错了、镜像站还没同步这个代号、或者第三方源不支持你这个架构。排查方法是从报错里把完整 URL 抠出来用浏览器或curl -I直接访问curl -I http://mirrors.example.edu.cn/ubuntu/dists/noble/InRelease能返回 200 说明路径没问题问题在别处返回 404 就顺着往上试试到哪一级开始 404就知道是哪一段写错了。Hash Sum mismatch更烦人意思是下载下来的索引文件内容和仓库声明的校验值不一致。常见原因是中间有缓存服务器返回了过期内容或者本地/var/lib/apt/lists/里残留了半截文件。处理办法sudo rm -rf /var/lib/apt/lists/* sudo apt update如果还报检查是否有 HTTP 代理或者换一个镜像站试试。极少数情况是镜像站同步到一半索引和包体版本不匹配等几个小时同步完就好了。5.3 依赖冲突与版本锁定当你从多个来源装了同一个包的不同版本apt install会开始报一堆held broken packages。这时候需要apt-cache policy查清楚各来源的版本apt-cache policy libfoo-dev输出会列出每个源提供的版本和当前的优先级默认 500。要压制某个源用 pinning# /etc/apt/preferences.d/no-example Package: * Pin: origin example.com Pin-Priority: 100优先级低于 500 意味着只有当没有更高优先级的候选时才用这个源设成负数等于禁用设成 1001 则是强制降级安装。这个机制在需要固定某个包版本时很有用比如生产环境要卡住某个库不让它升级。5.4 常见问题速查表报错关键词大概率原因处理方式NO_PUBKEY缺少仓库公钥下载公钥到/etc/apt/keyrings/并在Signed-By引用EXPKEYSIG公钥已过期重新拉取并替换密钥文件404 Not Found代号/组件/路径写错或镜像未同步curl -I逐级验证 URLHash Sum mismatch本地索引残留或中间缓存过期清空/var/lib/apt/lists/后重试Release file expired镜像站同步滞后换镜像站或临时切回官方源Could not resolveDNS 或网络问题检查/etc/resolv.conf和连通性Conflicting values新旧格式重复定义同一仓库清理重复的源文件Unable to locate package组件未开启检查是否包含universe组件6. 组合场景局域网缓存、离线源与自动化单机换源很简单但在真实环境里你面对的往往是几十台机器、无法直连外网的隔离网络、或者需要批量重建的 CI 环境。这一节讲三种实际用得上的组合方案。6.1 局域网统一缓存一台机器当二道贩子思路是找一台能上网的机器在上面跑一个缓存服务其他机器把源指向它。这样多个机器重复下载同一个包时实际只从上游拉一次。安装很简单sudo apt install -y apt-cacher-ng默认监听 3142 端口。其他机器的源配置改成指向这台机器的 IPTypes: deb URIs: http://192.168.1.10:3142/mirrors.example.edu.cn/ubuntu/ Suites: noble noble-updates noble-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg注意 URL 的构造方式http://缓存机IP:3142/后面直接接原始仓库域名和路径中间的http://要去掉。这个写法第一次看到容易写错多试两次就记住了。缓存会积累在/var/cache/apt-cacher-ng/长期跑下来可能占几十 GB需要配个清理策略比如在/etc/apt-cacher-ng/acng.conf里调整ExThreshold和ExTreshold相关参数或者定期手工清理。注意缓存机对上游是明文 HTTP内网环境安全性可控但如果内网本身不可信应该考虑搭配签名校验——好在 apt 本身就会校验包签名缓存机即使被篡改也无法伪造通过校验的包这一层是松不了的。这也是 apt 这个设计比单纯的文件服务器更稳的地方。6.2 内网隔离环境的离线源完全不能出网的机器做法是找一台同版本、能出网的机器把包下全了搬进去。# 在能出网的机器上下载指定包的完整依赖树 apt-get install --download-only -y nginx # 或者下载某个包的完整闭包 apt-get download $(apt-rdepends nginx | grep -v ^ | sed s/debconf-2.0/debconf/g)--download-only把.deb放在/var/cache/apt/archives/里然后拷贝到目标机器对应的目录apt install时它会优先用本地已有的包。如果目标机器数量多更规范的做法是用dpkg-scanpackages建一个本地仓库cd /srv/offline-repo dpkg-scanpackages . /dev/null | gzip -9c Packages.gz然后在客户端源里指向本地路径Types: deb URIs: file:/srv/offline-repo Suites: ./ Components: Signed-By: /etc/apt/keyrings/local.gpg Trusted: yes离线源通常自己签不出来所以会用到Trusted: yes。这在内网物理隔离的场景下是可接受的但一定要清楚这是拿掉了校验环节仓库目录的写权限必须严格限制。6.3 把源配置交给自动化如果你经常重建虚拟机手工改源太慢把它写进 cloud-init 的bootcmd或者 Ansible 的 task 里更省事。cloud-init 的写法#cloud-config apt: primary: - arches: [amd64, arm64] uri: http://mirrors.example.edu.cn/ubuntu/ security: - arches: [amd64, arm64] uri: http://mirrors.example.edu.cn/ubuntu/ sources_list: | Types: deb URIs: http://mirrors.example.edu.cn/ubuntu/ Suites: $RELEASE $RELEASE-updates $RELEASE-security Components: main restricted universe multiverse Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpgcloud-init 内部会处理$RELEASE变量替换比你在模板里手写代号更通用。Ansible 那边用ansible.builtin.deb822_repository模块参数化的程度更高还能顺手处理密钥下载和校验。有一个踩过的坑值得分享自动化脚本里apt update之后一定要检查返回码。有时候镜像站临时不可达apt update会返回非零但在某些 shell 配置下被忽略后续安装就莫名其妙失败。用set -e或者显式判断|| exit 1都能避免这个隐蔽问题。另外批量环境里镜像站的选择要考虑容量。所有人都指向同一个镜像站时如果镜像站的带宽有限反而会互相挤。有条件的话在局域网部署 6.1 说的缓存层让所有机器走本地缓存对外只保持一个出口这是最稳的结构。我个人的习惯是每台新机器装完之后第一件事就是确认源的代号和四组件是否齐全第二件事是跑一次apt update看输出里有没有异常源。这两步花不了一分钟但能省掉后面很多莫名其妙的排查时间。踩过几次代号写成旧版本导致装了老库然后整个编译环境崩掉的坑之后我宁可每次多看一眼。
