Ubuntu 22.04 安装 fdroidserver 2.4.5 指南

目标：在 Ubuntu 22.04 LTS 服务器上从零安装 fdroidserver 2.4.5，完成仓库初始化、APK 入库生成签名索引，并把仓库以静态文件方式发布到局域网供 F-Droid 客户端访问。本文全部命令与回显均为 2026-10-28 在真实 Ubuntu 22.04 服务器上的实测记录，逐条可复核。生态背景与选型对比见《F-Droid 介绍与选型指南》。

本系列另外两篇实操文档：配置参数逐项详解见《fdroidserver 2.4.5 配置参数详解》，命令族详解与备份恢复闭环见《fdroidserver 2.4.5 常用 CLI 命令与工具详解》。

一、实测环境

说明：fdroidserver 是纯命令行工具链，产出的仓库是纯静态文件（APK + 签名索引 + 图标），不包含需要常驻的服务进程。本文的「部署」指装好工具、生成仓库文件，并让这些文件可通过 HTTP 被客户端访问。

二、前置条件

1. Python ≥ 3.9：fdroidserver 2.4.5 的硬性要求（官方 PyPI 分类器列出对 3.9～3.14 的支持）。Ubuntu 22.04 自带 3.10.12，直接满足：

   $ python3 --version
   Python 3.10.12
   

2. JDK：APK 签名校验与索引签名环节要调用 apksigner/jarsigner 等 Java 工具：

   $ apt-get install -y openjdk-17-jdk-headless
   

   实测安装版本为 17.0.20.1+1-1~22.04（dpkg -l openjdk-17-jdk-headless）。

3. git：fdroid checkupdates 等命令要求仓库目录是 git 仓库（实测：非 git 目录执行会直接抛出 subprocess.CalledProcessError: Command '['git', 'status', '--porcelain']' returned non-zero exit status 128.，详见本系列命令篇）。

4. 网络：在线安装需访问 pypi.org；f-droid.org 与 GitHub 在部分网络环境需要代理。完全无外网的发布机走本文第五节离线方案。

三、版本选型：三条安装路径

选型依据（2026-10-28 实测）：

• Ubuntu 22.04 官方仓库只有旧版，apt-cache policy fdroidserver 逐字回显：

  fdroidserver:
    Installed: 2.1-1
    Candidate: 2.1-1
    Version table:
   *** 2.1-1 500
          500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages
          100 /var/lib/dpkg/status
  

• PyPI 实装 2.4.5 一次成功。自建仓库面向客户端分发，索引格式与签名逻辑随版本演进，没有理由主动选择落后近一年的 apt 版。

• PPA（add-apt-repository ppa:fdroid/fdroidserver）是官方安装文档给出的 Ubuntu 推荐路径之一，可获得较新的 apt 包；本文服务器未启用 PPA，不提供实测回显，读者按官方文档操作即可。

四、方案一：PyPI 在线安装（推荐）

$ pip install fdroidserver

实测回显（完整日志 217 行，节选）：

Collecting fdroidserver
  Using cached fdroidserver-2.4.5.tar.gz (8.3 MB)
...
Successfully installed GitPython-3.2.1 Mako-1.4.3 MarkupSafe-3.0.4 Pillow-12.3.0
PyYAML-6.0.3 alembic-1.20.1 androguard-4.1.4 apache-libcloud-3.9.1
apkInspector-1.3.7 argcomplete-3.7.2 args-0.1.0 asn1crypto-1.5.1 asttokens-3.0.2
bcrypt-5.0.0 certifi-2026.10.23 cffi-2.1.1 charset_normalizer-3.5.2 click-8.5.0
clint-0.5.1 colorama-0.4.6 cryptography-50.0.2 dataset-2.0.0 decorator-5.3.1
defusedxml-0.7.1 exceptiongroup-1.3.1 executing-2.3.0 fdroidserver-2.4.5
gitdb-4.0.12 greenlet-3.5.6 idna-3.20 invoke-3.0.3 ipython-8.39.0 jedi-0.20.1
loguru-0.7.3 lxml-6.1.3 matplotlib-inline-0.2.2 mutf8-1.1.0 networkx-3.4.2
oscrypto-1.3.0 paramiko-5.1.0 parso-0.8.7 pathspec-1.1.1 pexpect-4.9.0
platformdirs-4.12.4 prompt_toolkit-3.0.53 ptyprocess-0.7.0 pure-eval-0.2.4
puremagic-1.30 pycparser-3.11 pydot-4.0.1 pygments-2.21.0 pynacl-1.6.2
pyparsing-3.3.3 python-vagrant-1.0.0 qrcode-8.2 requests-2.34.2
ruamel.yaml-0.17.21 ruamel.yaml.clib-0.2.15 sdkmanager-0.7.2 smmap-5.0.3
sqlalchemy-2.0.55 stack_data-0.6.3 tomli-2.5.0 traitlets-5.16.1
typing-extensions-4.16.0 urllib3-2.8.0 wcwidth-0.9.4 yamllint-1.38.0

要点解读：

1. 依赖规模：连同 fdroidserver 本体共 68 个包，含 androguard（APK 解析）、GitPython、cryptography、apache-libcloud（云发布）、sdkmanager 等，一次装入。

2. 安装形态：fdroidserver 本体是 sdist 源码包（fdroidserver-2.4.5.tar.gz 8.3 MB），pip 在安装时本机构建，需要 setuptools（系统 Python 自带）。

3. 入口位置：root 环境全局安装时落在 /usr/local/bin/fdroid：

   $ which fdroid
   /usr/local/bin/fdroid
   $ fdroid --version
   2.4.5
   

4. root 身份直接 pip 安装会收到 pip 的 WARNING: Running pip as the 'root' user ... 提示，功能无影响；生产环境更规范的做法是装进独立 venv（venv 前置条件见第五节坑 1）。

五、方案二：离线安装（隔离网络发布机）

适用场景：发布机无外网（隔离网络分发正是 F-Droid 自建的典型场景之一）。核心思路——在联网机上用 pip wheel 把 fdroidserver 与全部依赖预构建为 wheel 包，拷贝到离线机后用 --no-index 纯本地安装。

5.1 联网机制作离线包

$ pip wheel fdroidserver -w /srv/fdroid-offline

实测产出 68 个 .whl 文件（与在线安装的 68 包一一对应）。pip wheel 会把 sdist 包（fdroidserver、args、clint、Mako 等）在本机构建为 wheel，并连带解析构建期依赖。

5.2 传输到离线机

$ scp -r /srv/fdroid-offline user@offline-server:/srv/fdroid-offline

（U 盘等物理介质同样适用。）

5.3 离线机安装与验证

$ apt-get install -y python3.10-venv
$ python3 -m venv /opt/fdroid-venv
$ /opt/fdroid-venv/bin/pip install --no-index --find-links /srv/fdroid-offline fdroidserver
$ /opt/fdroid-venv/bin/fdroid --version
2.4.5

实测 Successfully installed ... fdroidserver-2.4.5 ...（68 包全量落位），fdroid --version 输出 2.4.5，退出码 0——离线安装零构建步骤一次成功。

5.4 实测踩坑记录（逐字回显）

坑 1：未装 python3.10-venv 时 venv 创建失败。 Ubuntu 把 venv/ensurepip 拆在独立包里：

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.10-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

坑 2：pip download 打的包离线装不上。 若用 pip download fdroidserver -d <目录>（只下载、不构建），sdist 包在离线机的隔离构建环境里要现拉构建依赖，--no-index 下直接报错：

ERROR: Could not find a version that satisfies the requirement setuptools>=40.8.0 (from versions: none)
ERROR: No matching distribution found for setuptools>=40.8.0

实测补齐 setuptools/wheel 后，Mako 的构建后端接着要求 babel，逐个补齐不可穷举。结论：离线分发必须用 pip wheel 预构建全量 wheel，让所有构建步骤留在联网机完成。

六、方案三：发行版仓库（apt）

$ apt-get install -y fdroidserver

实测要点：

1. 版本偏旧：jammy/universe 仅 2.1-1（回显见第三节）。
2. 依赖体量大：默认连带推荐依赖，实测安装涉及 770+ 个 deb（configure 阶段出现 qemu-system-gui、gstreamer 等构建链组件），首次安装耗时明显；只想要工具本体可加 --no-install-recommends。
3. 命令位置：/usr/bin/fdroid（dpkg -S /usr/bin/fdroid → fdroidserver: /usr/bin/fdroid）。
4. 与 pip 共存时的版本错位现象：见第十节 FAQ 第 1 条，这是 apt 版最值得警惕的坑。
5. 还原：apt-get remove -y fdroidserver，实测回显 Removing fdroidserver (2.1-1) ...（释放 2063 kB）；/usr/bin/fdroid 消失，pip 装的 /usr/local/bin/fdroid 不受影响。连带装上的推荐依赖可按标准 apt 行为用 apt-get autoremove 清理。

七、三条路径对比

八、安装后配置：从 init 到局域网可访问

8.1 fdroid init 初始化仓库

$ mkdir -p /root/repo-b1 && cd /root/repo-b1
$ fdroid init

实测回显（ANDROID_HOME 未设置时）：

ERROR: No Android SDK found!
ERROR: You can use ANDROID_HOME to set the path to your SDK, i.e.:
ERROR: 	export ANDROID_HOME=/opt/android-sdk

Built repo based in "/root/repo-b1" with this config:

  Android SDK:			/opt/android-sdk
  Keystore for signing key:	keystore.p12

To complete the setup, add your APKs to "/root/repo-b1/repo"
then run "fdroid update -c; fdroid update".  You might also want to edit
"config.yml" to set the URL, repo name, and more.  You should also set up
a signing key (a temporary one might have been automatically generated).

For more info: https://f-droid.org/docs/Setup_an_F-Droid_App_Repo
and https://f-droid.org/docs/Signing_Process

解读与实测产物：

1. 开头的 ERROR: No Android SDK found! 只是 ANDROID_HOME 未设置的提示，init 仍以退出码 0 完成，生成 config.yml（18446 B）、keystore.p12（4294 B）与 repo/ 目录。只发布 APK（不自建源码构建）不需要完整 Android SDK；本文服务器上装有 build-tools 34.0.0（fdroid update 签名索引时调用其 apksigner）。

2. init 生成的 config.yml 中仅 6 个实体键，其余全部是注释态模板（完整参数见本系列配置篇）：

   sdk_path: /opt/android-sdk
   repo_keyalias: fdroid-server
   keystore: keystore.p12
   keystorepass: lje//cM3…（实测生成的随机密码，此处脱敏）
   keypass: lje//cM3…（同上）
   keydname: CN=fdroid-server, OU=F-Droid
   

   注意密码键名是 keystorepass/keypass（无下划线）。repo_url、repo_name 等在 init 产物里是注释态（# repo_url: https://MyFirstFDroidRepo.org/fdroid/repo），需要取消注释后按实际环境修改。

3. 仓库签名密钥指纹（keytool -list -keystore keystore.p12 实测）：

   Keystore type: PKCS12
   Your keystore contains 1 entry
   
   fdroid-server, Oct 28, 2026, PrivateKeyEntry,
   Certificate fingerprint (SHA-256):
   10:D4:37:3F:83:1F:8B:67:BF:EA:3F:BF:4D:C4:0E:A0:EA:EC:24:C1:F9:D4:7A:E7:0C:34:BE:9D:60:C1:B9:6F
   

   这串指纹就是客户端添加仓库时校验的信任锚，config.yml 与 keystore.p12 必须异地备份（备份恢复闭环实测见本系列命令篇）。

8.2 APK 入库并生成签名索引

把 APK 文件放进 repo/ 目录后执行：

$ fdroid update --create-metadata

实测回显（F-Droid 官方客户端 APK 入库）：

INFO: Using /opt/android-sdk/build-tools/34.0.0/apksigner
WARNING: repo_icon "repo/icons/icon.png" does not exist! Check "config.yml".
INFO: Generated skeleton metadata for org.fdroid.fdroid
INFO: Creating signed index with this key (SHA256):
INFO: 10 D4 37 3F 83 1F 8B 67 BF EA 3F BF 4D C4 0E A0 EA EC 24 C1 F9 D4 7A E7 0C 34 BE 9D 60 C1 B9 6F
WARNING: repo_icon "repo/icons/icon.png" does not exist, generating placeholder.
INFO: Finished

要点：

1. --create-metadata 为新入库应用自动生成骨架元数据 metadata/org.fdroid.fdroid.yml（实测内容）：

   AuthorName: ''
   Categories:
   - repo-b1
   CurrentVersionCode: 2147483647
   IssueTracker: ''
   Name: F-Droid
   SourceCode: ''
   Summary: ''
   WebSite: ''
   

   建议随后人工补全 Name/Summary/Categories 等字段；CurrentVersionCode: 2147483647 是骨架默认值，需要按实际版本修正。

2. WARNING: repo_icon ... does not exist 是未放置仓库图标所致，fdroid 会自动生成占位图标，不影响索引可用；在 repo/icons/icon.png 放入图标即可消除。

3. 签名索引使用的密钥指纹与 8.1 的 keytool 输出一致（10 D4 37 3F ...）。此后增量维护只需重跑 fdroid update（无参数）。

8.3 仓库发布与局域网访问验证

fdroidserver 产出的是纯静态文件，任意静态 Web 服务器都能发布。本文用 Python 内置 HTTP 服务验证分发通路（生产环境建议 Nginx 或 systemd 托管同等命令）：

$ python3 -m http.server 8149 --directory /opt/labdata
$ rsync -a /root/repo-b1/repo/ /opt/labdata/fdroid/repo/

客户端（F-Droid 官方客户端或 Droid-ify、Neo Store 等兼容客户端）添加仓库地址：

http://10.89.73.2:8149/fdroid/repo

局域网客户端实际访问的服务端日志（实测摘录）：

10.89.73.1 - - [28/Oct/2026 13:52:31] "GET /fdroid/repo/entry.json HTTP/1.1" 200 -
10.89.73.1 - - [28/Oct/2026 13:52:32] "HEAD /fdroid/repo/index-v1.jar HTTP/1.1" 200 -

客户端依次拉取 entry.json 与索引 JAR 并校验签名，两条 200 即分发通路验证通过。systemd 托管的参考写法（生产建议，把上面的验证命令交给服务管理器）：

[Unit]
Description=F-Droid repository static file server
After=network.target

[Service]
ExecStart=/usr/bin/python3 -m http.server 8149 --directory /opt/labdata
Restart=on-failure

[Install]
WantedBy=multi-user.target

⚠️ 仓库地址 URL 必须指向 repo 目录本身（形如 …/fdroid/repo）；归档仓库 archive 有独立地址与独立索引，由 archive_url 参数控制，详见本系列配置篇。

九、升级与降级

$ pip install -U fdroidserver          # 升级到 PyPI 最新稳定版
$ pip install fdroidserver==2.4.5      # 锁定/回退到指定版本

• fdroidserver 稳定版大约每季度到每半年发布一版（2.4.0 → 2.4.5 节奏见选型指南），自建仓库无需追 master。
• apt 与 pip 并存时升级互不影响（两套入口在不同路径），但强烈建议只保留一套，理由见 FAQ。
• 升级后重跑 fdroid update 重建索引即可，仓库数据与密钥不受工具升级影响。

十、常见问题（实测取证）

Q1：fdroid --version 打印的版本与 apt 包版本对不上？

Ubuntu jammy 的 fdroidserver 包是 2.1-1，但当系统同时存在 pip 安装的 2.4.5 时，/usr/bin/fdroid（apt 的 2.1 版 CLI）执行 --version 也会打印 2.4.5——CLI 入口脚本 import fdroidserver 时按 Python 模块搜索路径优先解析到 /usr/local 下的新版库。实测取证：

$ dpkg -S /usr/bin/fdroid
fdroidserver: /usr/bin/fdroid
$ dpkg -l fdroidserver | tail -1
ii  fdroidserver   2.1-1   all   F-Droid build server and repository tools for Android
$ /usr/bin/fdroid --version
2.4.5
$ python3 -c "import fdroidserver; print(fdroidserver.__file__)"
/usr/local/lib/python3.10/dist-packages/fdroidserver/__init__.py

规避方法：apt 与 pip 二选一；或 pip 一律装进 venv 并用 venv 的绝对路径调用。

Q2：python3 -m venv 报 ensurepip is not available？

Ubuntu 把 venv 能力拆在独立包里：apt-get install -y python3.10-venv 后重建 venv（完整回显见第五节坑 1）。

Q3：离线安装报缺 setuptools/babel？

pip download 只打包运行依赖，sdist 在离线机安装时要现拉构建依赖。改用 pip wheel 在联网机预构建全量 wheel（第五节）。

Q4：fdroid init 报 No Android SDK found!？

仅发布 APK 可忽略——init 仍会生成配置与签名密钥（实测退出码 0）。只有运行 build 等源码构建类命令才需要完整 SDK 并 export ANDROID_HOME=/opt/android-sdk。

Q5：反复出现 repo_icon "repo/icons/icon.png" does not exist WARNING？

init 后未放置仓库图标。fdroid 会自动生成占位图标（回显可见 "generating placeholder"），功能不受影响；把图标放到 repo/icons/icon.png 并在 config.yml 确认 repo_icon 指向该路径即可消除。

Q6：apt 装完找不到 fdroid 命令？

apt 版入口是 /usr/bin/fdroid，确认 dpkg 状态为 ii（安装中断会停留在 iU 半配置态，可用 DEBIAN_FRONTEND=noninteractive dpkg --configure -a 补完——本文实测 apt 安装曾因交互式 tzdata 配置卡住，kill 后由此命令恢复）。

十一、卸载

$ pip uninstall fdroidserver       # pip 安装的卸载
$ apt-get remove -y fdroidserver   # apt 安装的卸载（实测释放 2063 kB）

• pip 卸载只移除 fdroidserver 本体与入口，68 个依赖包保留；干净还原建议直接删除整个 venv 重建。
• 仓库数据与工具安装是分离的：config.yml、keystore.p12、metadata/、repo/ 都在仓库目录里，卸载工具不碰它们。删除仓库前务必先备份签名密钥（tar 打包与恢复验证见本系列命令篇）。

十二、参考与延伸阅读

• 官方安装文档《Installing the Server and Repo Tools》：https://f-droid.org/docs/Installing_the_Server_and_Repo_Tools
• 官方仓库搭建指南《Setup an F-Droid App Repo》：https://f-droid.org/docs/Setup_an_F-Droid_App_Repo
• fdroidserver PyPI 项目页：https://pypi.org/project/fdroidserver/
• fdroidserver 源码仓库：https://gitlab.com/fdroid/fdroidserver
• 本系列文档：
  • 生态认知与选型：《F-Droid 介绍与选型指南》
  • 配置参数逐项详解：《fdroidserver 2.4.5 配置参数详解》
  • 命令族实测与备份恢复闭环：《fdroidserver 2.4.5 常用 CLI 命令与工具详解》