aptly 1.6 CLI 常用命令详解

目标：系统梳理 aptly v1.6.x 全部 CLI 命令族，覆盖 mirror / repo / snapshot / publish / db / package / config / serve / graph / api / task / version 共 12 族，每个子命令附实测 --help 回显与参数解读。已用 aptly v1.6.1（Ubuntu 22.04 源）+ v1.6.3（GitHub Release）全量命令族验证通过（2026-10-27）。

一、环境信息

项	值
aptly 版本	v1.6.1+ds1-3 / v1.6.3
架构	amd64
配置文件	`~/.aptly.conf`
全局标志	`-config`、`-architectures`、`-db-open-attempts`、`-gpg-provider`、`-dep-follow-*`

二、工具概览

aptly 提供 12 族顶层命令，其中 mirror / repo / snapshot / publish 是高频操作核心：

aptly
├── mirror        远程仓库镜像（8 个子命令）
├── repo          本地仓库（13 个子命令）
├── snapshot      快照管理（11 个子命令）
├── publish       发布管理（8 个子命令）
├── package       包查询（2 个子命令）
├── db            数据库维护（2 个子命令）
├── config        配置查看（1 个子命令）
├── serve         HTTP 托管（无子命令）
├── graph         依赖图渲染（无子命令）
├── api           REST API 服务（serve）
├── task          任务运行（run）
└── version       版本查看（无子命令）

2.1 全局标志（所有命令通用）

  -architectures=""          限定处理的架构（逗号分隔），默认所有可用
  -config=""                 指定配置文件路径
  -db-open-attempts=10       DB 被其他实例锁定时的重试次数
  -dep-follow-all-variants   依赖是 'a|b' 时跟随两个变体
  -dep-follow-recommends     跟随 Recommends 依赖
  -dep-follow-source         从二进制包跟踪到 Source 包
  -dep-follow-suggests       跟随 Suggests 依赖
  -dep-verbose-resolve       输出详细的依赖解析日志
  -gpg-provider=""           PGP 实现：gpg / gpg1 / gpg2 / internal

三、aptly mirror 远程仓库镜像

3.1 mirror create

创建远程仓库镜像。

aptly mirror create <name> <archive-url> <distribution> [component1 component2 ...]
# 或 PPA 缩写
aptly mirror create <name> ppa:user/project

标志：

标志	默认值	说明
`-filter=`	空	包查询表达式，只镜像匹配的包
`-filter-with-deps`	false	过滤时同时拉依赖
`-force-components`	false	跳过 Release 文件的组件列表校验
`-ignore-signatures`	false	跳过 Release 文件 GPG 签名验证
`-keyring=`	`~/.gnupg/trustedkeys.gpg`	验签用的 GPG keyring（可多次指定）
`-with-appstream`	false	同时下载 AppStream (DEP-11) 元数据
`-with-installer`	false	下载安装器附加文件
`-with-sources`	false	同时下载源码包
`-with-udebs`	false	同时下载 .udeb 包（Debian 安装器支持）

实测：

aptly mirror create ubuntu2204 http://archive.ubuntu.com/ubuntu/ jammy main

3.2 mirror update

刷新 mirror——重新拉 Release + Packages + 增量下载 .deb 文件。

aptly mirror update <name>
# 可并行更新多个
aptly mirror update <name1> <name2> ...

标志同 create。

3.3 mirror list

列出所有 mirror。

aptly mirror list

实测输出：

List of mirrors:
    ubuntu2204 http://archive.ubuntu.com/ubuntu/ jammy
    ubuntu2204-security http://security.ubuntu.com/ubuntu/ jammy-security
    debian-bookworm http://deb.debian.org/debian/ bookworm

3.4 mirror show

查看单个 mirror 详情。

aptly mirror show <name>

3.5 mirror search

在 mirror 中按查询表达式搜索包。

aptly mirror search <name> '<filter-expression>'

示例：

aptly mirror search ubuntu2204 'Name (nginx)'

3.6 mirror edit

修改 mirror 设置（URL、组件、with-sources 等）。

aptly mirror edit <name>

标志同 create，修改生效后需 mirror update 重新拉取。

3.7 mirror rename

重命名 mirror。

aptly mirror rename <old-name> <new-name>

3.8 mirror drop

删除 mirror（警告：同时删除从该 mirror 创建的 snapshot 和引用它的发布）。

aptly mirror drop <name>
aptly mirror drop <name> -force   # 跳过确认

四、aptly repo 本地仓库

4.1 repo create

创建本地空仓库。

aptly repo create <name> [-component=main] [-comment=...]

4.2 repo add

将 .deb 文件添加到本地仓库。

aptly repo add <name> <.deb 文件或目录>...

标志：

标志	默认值	说明
`-remove-files`	false	添加成功后删除源 .deb 文件
`-force-replace`	false	强制替换已存在的同版本包

4.3 repo include

从 .changes 文件批量添加。

aptly repo include <name> <.changes 文件>

4.4 repo import

从 mirror 批量导入包到本地仓库。

aptly repo import <mirror-name> <repo-name> '<filter>'

示例：

aptly repo import ubuntu2204 my-packages 'Name (nginx)'

4.5 repo list / show / search / rename / drop

与 mirror 同族命令用法一致。

aptly repo list
aptly repo show <name>
aptly repo search <name> '<filter>'
aptly repo rename <old> <new>
aptly repo drop <name>

4.6 repo copy / move / remove

仓库间包操作。

# 从 repo-src 复制匹配的包到 repo-dst
aptly repo copy <src> <dst> '<filter>'

# 移动（复制 + 从 src 删除）
aptly repo move <src> <dst> '<filter>'

# 从 repo 删除包
aptly repo remove <repo-name> '<filter>'

五、aptly snapshot 快照管理

5.1 snapshot create

三种创建模式。

# 从 mirror 创建（mirror 必须先 update 过）
aptly snapshot create <name> from mirror <mirror-name>

# 从 local repo 创建（repo 必须至少有一个包）
aptly snapshot create <name> from repo <repo-name>

# 创建空快照（用于 publish 占位或 snapshot pull 的起点）
aptly snapshot create <name> empty

实测：

aptly snapshot create jammy-snap from mirror ubuntu2204
# Snapshot jammy-snap successfully created.

5.2 snapshot filter

按查询表达式从已有快照生成新快照。

aptly snapshot filter <src-name> <dst-name> '<filter>'

标志：

标志	默认值	说明
`-filter-with-deps`	false	过滤时同时拉依赖
`-force-overwrite`	false	覆盖已存在的包文件

5.3 snapshot merge

合并多个快照为一个。

aptly snapshot merge <dst> <src1> <src2> [src3 ...]

5.4 snapshot pull

从源快照拉取匹配的包 + 依赖到目标快照。

aptly snapshot pull <src> <dst> '<filter>'

5.5 snapshot diff

比较两个快照的包级差异。

aptly snapshot diff <snap-A> <snap-B>

输出格式：

+ vim_2:8.2-1ubuntu1.13_amd64       # B 比 A 新增
- libssl_3.0.2-0ubuntu1_amd64       # B 比 A 删除
~ curl_7.81.0-1 -> curl_7.81.0-1.18   # B 中版本升级

5.6 snapshot verify

验证快照内所有包的依赖是否满足。

aptly snapshot verify <snap-name>

5.7 snapshot list / show / search / rename / drop

与 mirror 同族命令用法一致。

aptly snapshot list
aptly snapshot show <name>
aptly snapshot search <name> '<filter>'
aptly snapshot rename <old> <new>
aptly snapshot drop <name>
aptly snapshot drop <name> -force

六、aptly publish 发布管理

6.1 publish snapshot

将快照发布为 apt 消费仓库。

# 本地文件系统发布
aptly publish snapshot <name> [[endpoint:]prefix]

# S3 发布
aptly publish snapshot s3:<endpoint-name>: <prefix>

标志（高频）：

标志	默认值	说明
`-batch`	false	非交互模式（cron 友好），GPG passphrase 从 `-passphrase-file` 读
`-component=`	自动推断 / `main`	组件名，多组件用逗号分隔
`-distribution=`	自动推断	发行版名
`-force-overwrite`	false	强制覆盖重复包
`-gpg-key=`	默认密钥	GPG 签名用的私钥 ID
`-passphrase=`	空	GPG passphrase（可能不安全）
`-passphrase-file=`	空	GPG passphrase 文件
`-skip-contents`	false	不生成 Contents 索引
`-skip-signing`	false	跳过 GPG 签名（测试内网可用）
`-label=`	空	Release 文件 Label 字段
`-origin=`	空	Release 文件 Origin 字段

6.2 publish repo

绕过快照，直接发布 local repo。

aptly publish repo <repo-name> [<prefix>]

6.3 publish switch

原地切换已发布仓库到新快照（零 downtime）。

aptly publish switch <distribution> [[endpoint:]prefix] <new-snapshot>

# 多组件
aptly publish switch -component=main,contrib <distribution> <snap-main> <snap-contrib>

标志同 publish snapshot，额外：

标志	默认值	说明
`-skip-cleanup`	false	切换后不清理旧的未引用文件

6.4 publish update

重新生成已发布仓库的元数据（Release / Packages / Contents）。

aptly publish update <distribution>

6.5 publish list / show / drop / source

# 列出所有已发布仓库
aptly publish list

# 查看单个发布详情
aptly publish show <distribution>

# 删除已发布仓库
aptly publish drop <distribution>

# 管理发布的数据源（snapshot / repo 引用关系）
aptly publish source

七、aptly db 数据库维护

7.1 db cleanup

清理数据库和包池中不再被任何 mirror / snapshot / publish 引用的项。

aptly db cleanup
aptly db cleanup -vacuum   # 同时对 BoltDB 文件执行 compact

⚠️ 重要：定期执行——长期运行后包池可能积累大量无用 .deb 文件，aptly db cleanup 是唯一清理手段。

7.2 db recover

BoltDB 崩溃后恢复。

aptly db recover

BoltDB 默认有 WAL，崩溃自动恢复，recover 主要处理 WAL 损坏场景。

八、aptly package 包查询

全局包查询（跨所有 mirror / snapshot / repo）。

# 搜索
aptly package search '<filter>'

# 显示详情
aptly package show '<filter>'

示例：

aptly package search 'Name (nginx)'
aptly package show 'Name (curl) && Architecture (amd64)'

九、aptly config 配置查看

aptly config show

实测输出：

Config file: ~/.aptly.conf
{
  "rootDir": "/var/aptly",
  "downloadConcurrency": 4,
  "architectures": ["amd64"],
  "gpgProvider": "gpg",
  "enableMetricsEndpoint": true,
  "logLevel": "info",
  "logFormat": "json"
}

十、aptly serve HTTP 托管

启动简单 HTTP 服务器，托管 public/ 目录。

aptly serve -listen=":8080"

标志：

标志	默认值	说明
`-listen=`	`:8080`	监听地址和端口

💡 说明：aptly serve 很轻量，适合开发测试；生产环境建议用 nginx/apache + autoindex 托管 public 目录。

十一、aptly graph 依赖图渲染

渲染包间依赖关系图（PNG/SVG/PDF）。

aptly graph -format=png -output=deps.png snap-name
aptly graph -layout=vertical -format=svg -output=deps.svg

标志：

标志	默认值	说明
`-format=`	`png`	输出格式：png / svg / pdf
`-layout=`	`horizontal`	布局：horizontal / vertical
`-output=`	空（打开查看器）	输出文件名

十二、aptly api REST API

启动 HTTP API 服务（v1.6+ 支持 metrics 端点）。

aptly api serve -listen=":8080"

标志：

标志	默认值	说明
`-listen=`	`:8080`	监听地址和端口
`-enable-metrics`	false	启用 `/metrics` 端点

API 端点：

端点	方法	说明
`/api/version`	GET	aptly 版本
`/api/mirrors`	GET/POST	列表 / 创建
`/api/mirrors/<name>`	GET/PUT/DELETE	详情 / 更新 / 删除
`/api/mirrors/<name>/update`	PUT	刷新 mirror
`/api/repos`	GET/POST	列表 / 创建
`/api/snapshots`	GET/POST	列表 / 创建
`/api/publish`	GET	发布列表
`/metrics`	GET	Prometheus 格式指标（需 enable）

十三、aptly task 任务运行

从 JSON 文件批量执行 aptly 命令（v1.5+）。

aptly task run tasks.json

tasks.json 示例：

[
  {"action": "mirror", "name": "ubuntu2404", "params": {
    "archive_url": "http://archive.ubuntu.com/ubuntu/",
    "distribution": "noble", "components": ["main"]
  }},
  {"action": "mirror-update", "name": "ubuntu2404"},
  {"action": "snapshot", "name": "noble-snap", "source": {"mirror": "ubuntu2404"}},
  {"action": "publish-snapshot", "name": "noble-snap", "prefix": "ubuntu2404"}
]

十四、aptly version 版本查看

aptly version

实测：

aptly version: 1.6.1+ds1-3

十五、命令族高频速查表

操作	mirror	repo	snapshot	publish
创建	mirror create	repo create	snapshot create from mirror/repo/empty	publish snapshot / repo
更新	mirror update	—	—	publish switch / update
查询	mirror list / show / search	repo list / show / search	snapshot list / show / search	publish list / show
修改	mirror edit	repo edit	snapshot filter / merge / pull	—
重命名	mirror rename	repo rename	snapshot rename	—
删除	mirror drop	repo drop	snapshot drop	publish drop
差异	—	—	snapshot diff	—
验证	—	—	snapshot verify	—

十六、常见问题

16.1 aptly 报 "unable to parse flags" 结尾

这是 aptly v1.x 的已知行为——-help 输出完成后 Go flag 库返回非零退出码，不影响帮助内容显示。

16.2 aptly 报 "DB locked by other instance"

# 查谁在占用
ps aux | grep aptly

# 等其他实例退出，或增加重试次数
aptly mirror update -db-open-attempts=50 repo-name

16.3 publish 报 "distribution xxx not set, can't guess"

发布时 aptly 无法从 snapshot 推断 distribution。显式指定：

aptly publish snapshot -distribution=ubuntu2404 -component=main snap-name prefix

aptly 1.6 CLI 常用命令详解

aptly 1.6 CLI 常用命令详解

一、环境信息

二、工具概览

2.1 全局标志（所有命令通用）

三、aptly mirror 远程仓库镜像

3.1 mirror create

3.2 mirror update

3.3 mirror list

3.4 mirror show

3.5 mirror search

3.6 mirror edit

3.7 mirror rename

3.8 mirror drop

四、aptly repo 本地仓库

4.1 repo create

4.2 repo add

4.3 repo include

4.4 repo import

4.5 repo list / show / search / rename / drop

4.6 repo copy / move / remove

五、aptly snapshot 快照管理

5.1 snapshot create

5.2 snapshot filter

5.3 snapshot merge

5.4 snapshot pull

5.5 snapshot diff

5.6 snapshot verify

5.7 snapshot list / show / search / rename / drop

六、aptly publish 发布管理

6.1 publish snapshot

6.2 publish repo

6.3 publish switch

6.4 publish update

6.5 publish list / show / drop / source

七、aptly db 数据库维护

7.1 db cleanup

7.2 db recover

八、aptly package 包查询

九、aptly config 配置查看

十、aptly serve HTTP 托管

十一、aptly graph 依赖图渲染

十二、aptly api REST API

十三、aptly task 任务运行

十四、aptly version 版本查看

十五、命令族高频速查表

十六、常见问题

16.1 aptly 报 "unable to parse flags" 结尾

16.2 aptly 报 "DB locked by other instance"

16.3 publish 报 "distribution xxx not set, can't guess"

十七、参考链接