Pacoloco - pacman 的缓存代理服务器

Pacoloco 是一个充当 Arch Linux pacman 仓库的 Web 服务器。每当 Pacoloco 服务器收到用户请求时，它会从真实的 Arch Linux 镜像下载该文件并将其转发给用户。此外，Pacoloco 会将此文件保存到本地文件系统缓存中，以便为未来的用户提供服务。它还允许预获取最近使用的软件包的更新。

目录

• 它有什么帮助？
• 安装
• 从源代码构建
• 配置
• 监控
• 处理多架构
• 故障排除
• 安全注意事项
• 致谢

它有什么帮助？

在世界许多地区，快速互联网仍然是一种奢侈品。由于地理和经济原因，许多地方的互联网访问既昂贵又缓慢。

现在考虑这样一种情况：多个 pacman 用户通过快速本地网络连接。这些用户中的每一个都需要下载相同的文件集。Pacoloco 通过缓存 pacman 文件内容并通过快速本地网络提供服务，从而最大限度地减少互联网负载。

Pacoloco 不会镜像整个 Arch 仓库。它只下载本地用户需要的文件。你可以将 Pacoloco 视为一个“惰性”Arch 镜像。

安装

Arch 系统

从官方 Arch 仓库安装 pacoloco 软件包。然后启动其 systemd 服务：

# systemctl start pacoloco

Docker

Pacoloco 可以与 Docker 一起使用。

你可以从 GitHub 的容器注册表获取预构建的镜像（另见侧边栏）。目前，镜像支持 amd64 和 ARM（arm64、armv7）架构。

docker pull ghcr.io/anatol/pacoloco

可用标签包括：latest = git master 以及所有 git 标签。

你也可以自己构建：

$ git clone https://github.com/anatol/pacoloco && cd pacoloco
$ docker build -t ghcr.io/anatol/pacoloco .

运行方式如下：

$ docker run -p 9129:9129 \
-v /path/to/config/pacoloco.yaml:/etc/pacoloco.yaml \
-v /path/to/cache:/var/cache/pacoloco \
ghcr.io/anatol/pacoloco

你需要提供路径或卷来存储应用程序数据。

或者，你可以使用 docker-compose：

---
services:
  pacoloco:
    # 如果提供了特定用户 ID，必须确保挂载的目录在主机上具有相同的用户 ID 所有者
    # user: 1000:1000
    container_name: pacoloco
    # 从 GitHub 注册表拉取镜像：
    image: ghcr.io/anatol/pacoloco
    # 或者替换为自构建：
    # build: https://github.com/anatol/pacoloco.git
    ports:
      - "9129:9129"
    volumes:
      - /path/to/cache:/var/cache/pacoloco
      - /path/to/config/pacoloco.yaml:/etc/pacoloco.yaml
    restart: unless-stopped
    # 为容器内的 cron 和日志时间戳设置时区：
    # environment:
    #   - TZ=Europe/Berlin

从源代码构建

需要 Go 1.25.0 或更高版本。

go build # 构建二进制文件
go test ./... # 运行测试

也可以选择使用 go build 命令从源代码构建二进制文件。

配置

服务器配置的默认位置是 /etc/pacoloco.yaml。

可以在启动 pacoloco 时使用 --config 参数更改配置文件位置，如下所示：

$ pacoloco --config /some/location/config.yaml

以下是配置文件的示例：

port: 9129
cache_dir: /var/cache/pacoloco
purge_files_after: 360000 # 360000 秒或 100 小时，0 表示禁用
download_timeout: 3600 # 下载将在 3600 秒后超时
repos:
  archlinux:
    urls:
      - http://mirror.lty.me/archlinux
      - http://mirrors.kernel.org/archlinux
  quarry:
    url: http://pkgbuild.com/~anatolik/quarry/x86_64
  sublime:
    http_proxy: http://bar.company.com:8989 # 可以为每个仓库启用代理，覆盖全局 `http_proxy`（见下文）
    url: https://download.sublimetext.com/arch/stable/x86_64
  archlinux-reflector:
    mirrorlist: /etc/pacman.d/reflector_mirrorlist # 注意！确保该文件中不包含 pacoloco URL！
http_proxy: http://foo.company.com:8989 # 仅当 pacoloco 在代理后运行时启用此选项
user_agent: Pacoloco/1.2
tls: # 可选部分，如果要为服务器启用 TLS，请添加此部分
  key: privatekey.pem
  cert: certificate.pem
prefetch: # 可选部分，如果要启用预获取，请添加此部分
  cron: 0 0 3 * * * * # 标准 cron 表达式（https://en.wikipedia.org/wiki/Cron#CRON_expression）定义预获取频率，详见 https://github.com/gorhill/cronexpr#implementation
  ttl_unaccessed_in_days: 30 # 默认 30，设置为大于系统连续未更新天数的值
  # 当软件包更新后 ttl_unaccessed_in_days 天内未被下载时，将删除并停止预获取该软件包（和数据库链接）
  ttl_unupdated_in_days: 300 # 默认 300，将删除并停止预获取那些在 ttl_unupdated_in_days 天内既未上游更新也未被请求的软件包

• cache_dir 是缓存目录，该位置需要服务器进程具有读写权限。
• purge_files_after 指定文件在缓存中不活动的持续时间（以秒为单位），超过此时间后文件将从缓存中删除。此功能使用Unix的“AccessTime”字段来识别不活动文件。默认值为0，表示永不执行清理。
• address 是服务器监听地址。若留空，服务器将在所有可用地址上启动监听器。如果任何IP是公网IP，pacoloco将对互联网开放。
• port 是服务器端口。
• download_timeout 是从互联网下载到缓存的超时时间（以秒为单位）。如果远程服务器速度缓慢导致文件下载时间超过此值，下载将被终止。默认值为0，表示无超时。
• repos 是要镜像的仓库列表。每个仓库需要指定名称（name）和其Arch镜像的URL（url）。注意，URL可以通过url或urls属性指定，每个仓库配置必须且只能使用其中一个。每个仓库可以有自己的http_proxy，这会覆盖全局的http_proxy（见下文）。
• http_proxy 仅在pacoloco运行在代理后方时使用。
• user_agent 是用于从仓库获取文件的用户代理。默认值为Pacoloco/1.2。
• tls 部分允许为服务器启用TLS加密。必须提供密钥（key）和证书（cert），且两者都必须可读。
• prefetch 部分允许启用软件包预取功能。注释掉此部分可禁用预取。
• 要测试cron值是否符合预期，请查看cronexpr实现或进行测试。
• 关于镜像列表（mirrorlist），确保所选的mirrorlist文件中不包含pacoloco自身。它也可以与reflector集成，方法是更改reflector的输出路径，或在/etc/pacman.conf中为标准仓库直接包含pacoloco（例如添加Server=...条目或仅包含pacoloco URL的自定义镜像列表文件）。

有关所有配置选项的详细参考，请参见docs/configuration.md。

[core]
Include = /etc/pacman.d/mirrorlist

[extra]
Include = /etc/pacman.d/mirrorlist

[quarry]
Server = http://yourpacoloco:9129/repo/quarry

[sublime-text]
Server = http://yourpacoloco:9129/repo/sublime

以及/etc/pacman.d/mirrorlist文件内容：

Server = http://yourpacoloco:9129/repo/archlinux/$repo/os/$arch

配置完成。从此，pacman请求将通过我们的pacoloco服务器进行代理。

监控

Pacoloco在/metrics端点暴露Prometheus指标。

可用指标

Prometheus 抓取配置

scrape_configs:
- job_name: 'pacoloco'
  static_configs:
  - targets: ['yourpacoloco:9129']

处理多架构

pacoloco作为纯粹的代理，不关心仓库的架构，因此可以透明地处理多种不同架构。一种实现方式是添加多个名称格式为foobar_$arch的仓库，例如：

repos:
  archlinux_x86_64:
    urls:
      - http://mirror.lty.me/archlinux
      - http://mirrors.kernel.org/archlinux
  archlinux_armv7h:
    url: http://mirror.archlinuxarm.org
  archlinux_x86:
    url: http://mirror.clarkson.edu/archlinux32

然后修改用户的/etc/pacman.d/mirrorlist并添加：

对于x86_64架构：

Server = http://yourpacoloco:9129/repo/archlinux_$arch/$repo/os/$arch

对于armv7h架构：

Server = http://yourpacoloco:9129/repo/archlinux_$arch/$arch/$repo

对于x86架构：

Server = http://yourpacoloco:9129/repo/archlinux_$arch/$arch/$repo

请注意，archlinux_$arch是pacoloco.yaml中的仓库名称。

故障排除

缓存目录权限

Pacoloco需要对缓存目录具有读写权限。如果出现类似“directory /var/cache/pacoloco does not exist or isn't writable”的错误，请执行以下操作：

sudo mkdir -p /var/cache/pacoloco
sudo chown pacoloco:pacoloco /var/cache/pacoloco

镜像列表循环引用

如果pacoloco自身的URL包含在仓库使用的镜像列表文件中，将导致无限循环。务必从pacoloco使用的镜像列表文件中排除pacoloco服务器。

TLS错误

使用TLS时，证书（cert）和密钥（key）文件必须存在且可被pacoloco进程读取。检查文件权限：

ls -la /path/to/cert.pem /path/to/key.pem

Cron表达式语法

Pacoloco使用7字段的cron表达式（秒、分、时、日、月、星期、年），这与标准的5字段cron不同。详情请参见cronexpr文档。

日志时间戳

默认情况下，pacoloco日志包含文件/行信息。要切换为时间戳，请在配置中添加：

set_timestamp_to_logs: true

清理间隔

purge_files_after的值以秒为单位，若启用则必须至少为600（10分钟）。设置为0将完全禁用清理。

安全注意事项

• 网络绑定：默认情况下，pacoloco监听所有接口。在生产环境中，建议设置address以仅绑定到特定接口（例如127.0.0.1或局域网地址）。
• TLS文件权限：确保TLS私钥文件仅对pacoloco用户可读（chmod 600）。
• 代理凭据：如果使用带凭据的http_proxy，请注意这些凭据以明文形式存储在配置文件中。相应地限制配置文件权限。
• 签名验证：Pacoloco不验证软件包签名，而是将此任务委托给pacman客户端。确保客户端已启用签名验证。

致谢

非常感谢所有为该项目做出贡献的人！没有你们的帮助，Pacoloco不可能取得成功。

---

项目仓库 README（补充）

Pacoloco - pacman的缓存代理服务器

Install

Arch 系统

从官方 Arch 仓库安装 pacoloco 包。然后启动其 systemd 服务：# systemctl start pacoloco。

Docker

Pacoloco 可与 Docker 一起使用。

您可以从 GitHub 的 https://github.com/anatol/pacoloco/pkgs/container/pacoloco 获取预构建镜像（另见侧边栏）。目前镜像支持 amd64 和 ARM（arm64、armv7）架构。

docker pull ghcr.io/anatol/pacoloco

可用标签：latest = git master 分支以及所有 git 标签。

您也可以自行构建：

$ git clone https://github.com/anatol/pacoloco && cd pacoloco
$ docker build -t ghcr.io/anatol/pacoloco .

运行方式如下：

$ docker run -p 9129:9129 \
-v /path/to/config/pacoloco.yaml:/etc/pacoloco.yaml \
-v /path/to/cache:/var/cache/pacoloco \
ghcr.io/anatol/pacoloco

您需要提供路径或卷来存储应用数据。

或者，您可以使用 docker-compose：

---
services:
pacoloco:
# if a specific user id is provided, you have to make sure
# the mounted directories have the same user id owner on host
# user: 1000:1000
container_name: pacoloco
# to pull the image from github's registry:
image: ghcr.io/anatol/pacoloco
# or replace it for for self-building with:
# build: https://github.com/anatol/pacoloco.git
ports:
- "9129:9129"
volumes:
- /path/to/cache:/var/cache/pacoloco
- /path/to/config/pacoloco.yaml:/etc/pacoloco.yaml
restart: unless-stopped
# to set time zone within the container for cron and log timestamps:
# environment:
# - TZ=Europe/Berlin

故障排除

缓存目录权限

Pacoloco 需要对缓存目录具有读写权限。如果您看到类似 directory /var/cache/pacoloco does not exist or isn't writable 的错误，请执行以下操作：

sudo mkdir -p /var/cache/pacoloco
sudo chown pacoloco:pacoloco /var/cache/pacoloco

镜像列表循环引用

如果 pacoloco 自身的 URL 被包含在某个仓库使用的镜像列表文件中，会导致无限循环。请始终从 pacoloco 所使用的镜像列表文件中排除 pacoloco 服务器。

TLS 错误

使用 TLS 时，cert 和 key 文件必须存在且可被 pacoloco 进程读取。检查文件权限：

ls -la /path/to/cert.pem /path/to/key.pem

Cron 表达式语法

Pacoloco 使用 7 字段 cron 表达式（秒、分钟、小时、日、月、星期、年），这与标准的 5 字段 cron 不同。详情请参见 https://github.com/gorhill/cronexpr#implementation%E3%80%82

日志时间戳

默认情况下，pacoloco 日志包含文件/行信息。要切换到时间戳，请在配置中添加：

set_timestamp_to_logs: true

清理间隔

purge_files_after 值以秒为单位，启用时必须至少为 600（10 分钟）。设为 0 会完全禁用清理功能。

非常感谢所有为该项目做出贡献的人！没有你们的帮助，Pacoloco 不可能取得成功。