用户指南

从源码构建 U 盘镜像

Town OS 的 U 盘镜像由 install 仓库构建。构建过程会生成一个可启动镜像，其根文件系统为 squashfs，分区表为 GPT。

先决条件

你需要一台 Linux 主机和一个 U 盘（4 GB 或更大）。构建使用 Arch Linux 的工具链 （pacstrap、mkinitcpio、arch-chroot）， 但你不需要运行 Arch——在其他发行版上，make image 会自动在同架构的 Arch 容器中执行构建。请用对应你发行版的目标安装主机依赖：

• make deps——Arch（及其衍生版）或 Fedora/RHEL
• make deps-debian——Debian 或 Ubuntu

它们会安装构建和虚拟机工具所需的一切——make、 podman、arch-install-scripts、squashfs-tools、 parted、e2fsprogs、dosfstools、 qemu 和 libvirt。

克隆与构建

git clone https://gitea.com/town-os/install.git
cd install
make image

运行 make 或 make image 即可构建完整的 U 盘镜像。 该过程会下载基础系统、安装 Town OS 组件、把所有内容压缩成 squashfs 文件系统， 并组装出带 GPT 分区表的最终磁盘镜像。

分区与 squashfs

生成的镜像采用 GPT 布局，包含：

• 一个 BIOS 引导分区（1 MiB），用于传统 BIOS 启动
• 一个 EFI 系统分区（64 MiB，FAT32），用于 UEFI 启动
• 一个数据分区（ext4），存放 squashfs 根文件系统和 GRUB

启动时，Town OS 会把 squashfs 挂载为只读的下层，并在其上叠加一层 tmpfs。 这意味着操作系统完全在内存中运行——U 盘本身只在启动时被读取。 所有运行期的改动都发生在内存中，重启后即被丢弃，每次都还你一块干净的白板。

写入镜像

最简单的方式是 make flash：镜像过期时会自动重新构建，然后写入 USB 设备。 如果要手动操作，请注意构建产物带有日期和架构后缀（例如 town-os-2026-07-25-x86_64.img）——用 dd 写入即可：

# 找到你的 USB 设备（例如 /dev/sdb）
lsblk

# 写入镜像（把文件名和 /dev/sdX 替换成你自己的设备）
sudo dd if=town-os-YYYY-MM-DD-x86_64.img of=/dev/sdX bs=4M status=progress conv=fsync

请再三确认目标设备——dd 会不加确认地覆盖你所指定的任何设备。

在路由器上设置 DNS

Town OS 内置了 rolodex， 这个 DNS 服务器为你的软件包管理权威区域，并转发上游查询。要把它用作整个网络的 DNS 服务器，你需要让路由器把 Town OS 机器的 IP 地址作为 DNS 服务器下发给网络中的设备。 这样每台设备都会自动使用 rolodex 解析 DNS——无需逐台配置。

找到 Town OS 的 IP 地址

你需要知道 Town OS 机器的局域网 IP 地址。可以通过以下方式找到：

• 首次启动配置完成后，登录 http://town-os.local 的仪表盘，取其中显示的内部 IP——这个地址就是要用作 DNS 服务器的地址
• 如果你用的是虚拟机，运行 make vm-ip
• 在路由器的 DHCP 客户端列表里查找名为「town-os」的设备

要让 DNS 稳定工作，Town OS 机器应当拥有静态 IP 地址，或在路由器上设置 DHCP 保留。 如果 IP 变了，整个网络的 DNS 都会失效。

分配静态 IP 或 DHCP 保留

大多数路由器都允许你根据 MAC 地址为特定设备保留 IP。这项设置通常位于 局域网设置、DHCP 或 地址保留 中。 在客户端列表里找到 Town OS 机器，把它当前的 IP 保留下来即可。

如果你的路由器不支持 DHCP 保留，也可以在 town-os.yaml 中添加配置， 直接在 Town OS 机器上设置静态 IP。

在路由器中修改 DNS 服务器

不同品牌的路由器操作细节各异，但大致流程是一样的：

1. 登录路由器的管理界面（通常是 192.168.1.1 或 192.168.0.1）
2. 找到 DHCP 设置、局域网设置 或 DNS 设置 部分
3. 把 首选 DNS 服务器 改成 Town OS 机器的 IP 地址
4. 可以再设置一个 备用 DNS 服务器 作为兜底（例如 1.1.1.1 或 8.8.8.8）——当 Town OS 无法访问时会用它
5. 保存并应用设置

保存之后，网络中的设备会在下一次续租 DHCP 时获得新的 DNS 服务器。 你也可以断开并重新连接网络，或者重启设备来立即生效。

常见路由器界面

关闭浏览器自带的 DNS

大多数浏览器都自带 DNS 解析器，会完全绕过你的路由器。 Firefox 的 DNS over HTTPS（DoH），以及 Chrome 和 Edge 中对应的「安全 DNS」功能， 都会把查询直接发给 Cloudflare、NextDNS 之类的公共服务商，因此 Town OS 根本看不到 这些查询，你的软件包域名就会显示「找不到服务器」，哪怕网络中其他设备都解析正常。 请在每一台需要按名称访问你服务的设备上关掉它：

• Firefox——设置 → 隐私与安全 → DNS over HTTPS，选择关闭。（默认保护也可能悄悄启用 DoH，所以请明确选「关闭」，不要保留默认值。）
• Chrome——设置 → 隐私和安全 → 安全，关闭使用安全 DNS。
• Edge——设置 → 隐私、搜索和服务 → 安全性，关闭使用安全 DNS 指定如何查找网站的网络地址。
• Brave、Vivaldi、Opera——与 Chrome 相同，位于隐私和安全 → 安全下。
• Safari——没有内置 DoH，使用系统解析器。请到系统设置 → 通用 → VPN 与设备管理确认没有安装 DNS 描述文件。

你可能配置过的任何系统级加密 DNS 也是同理——Android 的私人 DNS、 iOS/macOS 的 DNS 描述文件，或本地的 systemd-resolved/dnscrypt 配置。这些都会覆盖路由器下发的 DNS 服务器。如果你想要加密的上游 DNS，交给 Town OS 就好： rolodex 自己就能对上游使用 DoH/DoT，同时仍然解析你的本地名称 （见下文选择解析模式）。

验证是否生效

当设备获取到新的 DNS 设置后，验证一下 rolodex 是否真的在处理你的 DNS 查询：

# 查看你的机器正在使用哪个 DNS 服务器
nslookup example.com

# 或者直接向 Town OS 查询
dig @<town-os-ip> example.com

# 查询软件包域名（前提是你已经安装了软件包）。
# 名称形如 <name>.<repo>.<tld> —— .home 是默认网络的 TLD
dig @<town-os-ip> gitea.default.home

如果 example.com 能正确解析，说明 rolodex 已经在工作， 并在为你的网络处理 DNS。

选择解析模式

不属于你任何一个网络的名称，会按照解析模式来处理； 该模式在仪表盘的 设置 → DNS 解析 中设定。共有三种模式：

• 自动（推荐）——默认模式。先尝试从根服务器开始迭代解析，失败后依次回退到 DoH/DoT、本地转发器，最后是公共解析器，并沿用最近一次成功的层级。这样在网络条件允许时保留递归解析的隐私性，在过滤出站 DNS 的网络中也能优雅降级。
• 仅递归——全部从根服务器迭代解析，不做任何回退。可以保证查询绝不会交给第三方解析器，但在封锁或劫持出站 53 端口的网络（酒店、门户认证网络、某些 ISP）中，所有外部名称都会解析失败。
• 转发——始终把未匹配的查询发给上游解析器（默认是 Google Public DNS）。这就是传统的转发行为。

请注意，这项设置说的是本机如何访问互联网。而另一个方向上的加密 DNS—— 也就是你自己的设备用来访问本机的方式——将在下面介绍。

从你的设备使用加密 DNS

Town OS 不只为自己使用加密 DNS，也把它提供给你自己的设备。 共有三个可用端点，它们解析的名称与 53 端口上的普通 DNS 完全相同：

• DNS over HTTPS（DoH）——https://dns.<tld>/dns-query。它经由 ingress 走标准 HTTPS 端口，因此在限制严格的网络中最有可能可用。
• DNS over TLS（DoT）——dns.<tld>，853 端口。
• DNS over QUIC（DoQ）——dns.<tld>，853 端口，基于 UDP。

这三者出示的证书都由本机自己的证书颁发机构签发，所用的名称和地址与系统其余部分一致。 如果你已经在设备上安装了根 CA（参见 信任证书颁发机构），它们无需任何额外配置即可通过校验。

从未信任过你的 CA 的设备同样可以验证这些端点。 Town OS 会在它作为权威的区域中发布 DANE 记录来锚定该证书，分别位于 _853._tcp.dns.<tld> 与 _853._udp.dns.<tld>—— 每种传输各一条，因为支持 DANE 的客户端如果找不到自己所选传输对应的记录，就会以失败告终。 由于该设备本就能访问这台解析器，它就能取到这份锚定信息，从而在不预先安装任何东西的情况下， 校验自己收到的证书。

支持 DDR 的客户端会自行发现这一切。Town OS 会在 _dns.resolver.arpa（RFC 9462）发布指派记录，按优先级依次给出 DoH 的 URL 以及 DoT 和 DoQ 的端口——DoH 排在最前，因为 443 端口能够穿过那些封锁 853 的过滤。 只要把支持 DDR 的设备指向本机做普通 DNS，它就会自己发现并升级到加密端点。

这三个监听器是在启动时由安装镜像的配置打开的，因此与绝大多数 DNS 设置不同，它们无法从控制面板开启。 其背后的证书会在本机仅仅处于运行状态时于后台续期——无需重启—— 并且新的 DANE 锚定会在旧的撤下之前先行发布，因此不存在任何会让校验型客户端拒绝连接的时间窗口。

拦截恶意域名

rolodex 可以用公共黑名单筛查每一次查询，让你无需另装 Pi-hole 就能获得全网范围的威胁拦截。相关设置在 DNS → 黑名单 中管理。 黑名单提供方分为两类，作用对象各不相同：

• DNSBL（域名黑名单）——匹配被查询的名称。真正影响日常上网的是这一侧。
• RBL（实时黑洞列表）——匹配 IP 地址，而且只在反向 DNS 查询时生效。

两者都默认关闭，且提供方列表为空，并且都是按需查询的： Town OS 从不下载、解析或预缓存任何黑名单数据源。在你启用某一类并至少添加一个区域之前， 什么都不会被检查。

DNSBL 查询是如何工作的

被解析的名称会被拼接到提供方的区域之前，然后作为一次普通的 DNS 查询发出。 在启用 dbl.spamhaus.org 的情况下解析 badsite.example， 实际会发出对 badsite.example.dbl.spamhaus.org 的查询。

• 有应答即代表已列入——对于被列入的名称，提供方会返回一条地址记录（通常是 127.0.0.x）。rolodex 随后向发起查询的设备返回 NXDOMAIN。
• NXDOMAIN 即代表干净——解析照常继续。出错或超时的提供方一律视为未列入，因此一个无法访问的黑名单绝不会让你的网络断线。
• 黑名单胜过外部世界，但绝不胜过你自己的记录——检查发生在本地记录和软件包记录之后（所以 gitea.default.home 始终能解析），但在上游缓存和转发器之前，因此即便转发得到的应答已被缓存，被列入的名称仍会被拒绝。
• 按名称匹配，而非按后缀——doubleclick.net 被列入并不会连带拦截 stats.g.doubleclick.net，除非提供方也列入了那个名称。要不要因为一个主机而封掉整个域名，是你的决定，不该由数据源替你做主。
• 结果会短暂缓存——命中按提供方的 TTL 缓存，未命中缓存五分钟。

DNSBL 提供方

以下是仪表盘中可一键添加的选项。它们都仍在运营、免费，并且会应答自行递归的解析器、 无需注册——而 Town OS 正是这样一台设备。你也可以手动输入任何其他区域。

RBL 查询是如何工作的

IP 地址会被反转，然后拼接到提供方的区域之前。 用 zen.spamhaus.org 检查 192.168.1.100，实际发出的查询是 100.1.168.192.zen.spamhaus.org。IPv6 地址会展开为半字节并以同样方式反转。 有应答即代表已列入，NXDOMAIN 代表干净，缓存方式与 DNSBL 完全一致。

但要注意：RBL 区域只在反向 DNS 查询（in-addr.arpa 和 ip6.arpa）中查到的 IP 上生效，而普通的网页浏览几乎不会产生这类查询。 这些列表的存在意义，是让邮件服务器拒绝某个发起连接的发件方，那才是它们真正发挥价值的地方。 在家用路由器上，它们几乎等同于无操作——真正影响上网的是上面的 DNSBL 那一侧。 如果你在 Town OS 后面运行邮件服务，那就启用它们；否则值得你关注的是域名列表。

RBL 提供方

刻意不提供的列表

有三个知名区域被刻意排除在一键添加列表之外，因为它们都会无声地失效—— 你会看到已配置的提供方，于是误以为自己受到了保护。如果你清楚自己在做什么，仍然可以手动添加。

• SORBS（dnsbl.sorbs.net）——已于 2024 年 6 月 5 日停止服务，区域也被清空。它照样应答，只是永远不会列出任何东西：一个看起来像保护的永久空操作。
• Barracuda（b.barracudacentral.org）——免费，但需要先注册发起查询的 IP。未注册的机器可能先能用一阵子，然后被无预警地切断。
• UCEPROTECT 第 2、3 级——按整个网段和 ASN 收录，因此你的 ISP 上出了一个坏邻居，整个 ISP 都会被拦下。

本地条目与白名单

• 本地条目（DNS → 黑名单）——手动拦截某个特定域名或 IP，并在旁边记录理由。域名条目会让正向查询返回 NXDOMAIN，且立即生效。这项检查排在所有外部提供方之前，也正是你在不订阅整个数据源的情况下、拦掉某一台特定主机的方式。
• 白名单（DNS → 白名单）——误报时的逃生出口。被列入白名单的名称会直接跳过整个基于名称的检查：既不与 DNSBL 提供方比对，也不与你的本地条目比对，更不会为它发出任何提供方查询。与拦截不同，放行是按后缀匹配的——放行 vendor.example 也会一并放行 cdn.vendor.example。条目只能是名称，绝不能是 IP，因此反向 IP 的 RBL 路径不受影响。

该抱什么预期

这些数据源是为电子邮件而生的，不是为广告拦截。它们在钓鱼、恶意软件和 垃圾邮件载荷域名上表现出色，在广告和追踪器上则平平——那是可下载的 hosts 式数据源的活儿， 而 Town OS 刻意不去摄取它们。没有任何定时抓取、没有任何解析、也没有任何在你背后进行的缓存。 如果你想让某个广告或追踪域名消失，把它加为本地条目即可。

在 DNS 中发布服务

默认情况下，每个已安装的软件包服务都会在其 网络的 TLD 下发布到 DNS 中，这样你就能按名称访问它。 在 DNS → 服务 中，你可以逐个切换服务是否发布—— 未发布的服务照常运行，只是不能再按名称解析。每个服务的完全限定名称遵循 <name>.<repo>.<tld> 的形式（对默认网络而言，该 TLD 为 .home）。

网络与远程访问

Town OS 把你的服务按网络分组。每台设备开箱就带有一个名为 home 的内置网络——它仅限局域网，解析 .home 下的名称， 并且没有隧道。要从家门之外安全地访问你的服务，请再创建别的网络： 每一个都是一层 WireGuard 覆盖网络，配有自己的 DNS 顶级域， 在 仪表盘 → 网络 中管理（仅限管理员）。

默认网络

• 始终存在，无法删除。home 网络会自动创建，除非你另选其他网络，否则软件包都会落在这里。
• 仅限本地。它没有 WireGuard 传输层——.home 名称只在你的局域网内解析，并且刻意不向远程对端开放。
• 使用 .home 顶级域，该值来自 dns_tld 设置。

创建用于远程访问的网络

点击创建网络，给它起个名字（例如 office）， 并可选地指定一个 TLD（默认与网络名相同）。随后 Town OS 会：

• 生成一个 WireGuard 接口，其覆盖网子网由 10.64.0.0/10 范围内确定性地推导得出，本机占用 .1 地址。
• 占用该网络的 TLD（TLD 在每台设备上唯一——若创建的网络使用了别的网络已占用的 TLD，会被拒绝）。
• 在覆盖网上运行一个该网络专属的 DNS 解析器，使加入的设备能解析该网络的名称。

每一行上的远程访问开关用于启用或关闭该 WireGuard 接口。 关闭它会切断远程访问，但容器仍在运行，本地依然可以访问。

为设备办理登记

打开某个网络的对端对话框，输入设备名称，点击 添加对端。Town OS 会返回一份可直接导入的 WireGuard 配置—— 把它粘贴到手机或笔记本上的 WireGuard 应用中即可。

请立刻复制这份配置。它包含一把刚生成、从不留存的私钥—— 之后无法再取回，弄丢了就只能重新登记该设备。

生成的配置会把设备的 DNS 指向本机的覆盖网地址，因此隧道一旦建立， 你网络中的名称就会自动解析。普通设备请让运行 rolodex DNS 开关保持关闭；只有当某个对端自身运行着你希望转发过去的 rolodex DNS 服务器时才启用它。

仅限 WireGuard 的账户

如果你想让别人自行登记他们的设备，又不想把整个仪表盘交给他们，可以创建一个 仅限 WireGuard 的账户（创建用户界面上的一个复选框）。这类账户：

• 被限定在一个或多个特定网络上——只能在这些网络上登记对端，且永远不能用于 home 网络。
• 默认拒绝：它可以认证、登记和续期自己的对端、获取 CA，但控制面上的其他事情一概不能做。
• 登记的是会过期的对端。每次登记都带有一个有效期（默认 2 小时，可在 设置 → WireGuard 对端有效期 中调整），必须续期才能保持连接；被弃用的设备会自动过期。由管理员添加的对端则是永久的。

查看与断开对端

网络页面上的已连接对端面板会列出所有网络中已登记的每一个对端， 并显示实时握手状态、覆盖网 IP、已传输数据量和到期时间。要强制切断某台设备， 使用断开连接——它会移除该对端、立即拆除隧道并吊销其密钥， 因此该设备在重新登记之前无法再连上来。

在指定网络上安装软件包

安装对话框（以及 页面 对话框）里有一个 网络 选择器。 你选择的网络决定了该服务的 DNS 名称和 TLS 证书——安装在 office 上的软件包会在 .office 下解析，证书也按该名称签发。非默认网络上的服务是双栖的： 对隧道对端解析为覆盖网地址，对本地客户端解析为局域网地址。把软件包重装到另一个网络上， 会把它的 DNS 和证书一并迁到那个网络的 TLD 下。

举个例子，把 Jitsi 安装在 TLD 为 fart 的网络上，它会发布在 jitsi.default.fart。运行起来之后，该服务会以可点击链接的形式出现在你的 仪表盘上，网络中的任何设备都能直接打开。

用 U 盘镜像构建虚拟机

install 仓库中包含用于在虚拟机里启动 Town OS 的脚本，这在测试和开发时很有用—— 既可以用你从源码构建的镜像，也可以直接用 已经写好的实体 U 盘。 make help 会列出所有目标和变量。

QEMU

make qemu-fg

镜像过期时会先重新构建，然后在前台启动一台 QEMU 虚拟机， 附带串口控制台、KVM 加速，以及四块用于存储测试的虚拟数据盘。 这是你首选的目标：你可以在终端里直接看着启动过程和安装程序，按 Ctrl-C 即可停止虚拟机。 如果你希望它在后台运行，请改用 make qemu （稍后用 make serial 连接）， 而 make rebuild-qemu 则一步完成停止、清理、重建和重新启动。

虚拟机接入 libvirt 的 default NAT 网络（virbr0）， 并固定到 VM_IP（默认 192.168.122.50）， 因此同时运行多台虚拟机时，请给每台分配各自的地址。

由于客户机处于 NAT 之后，VM_LAN=1（默认值）会把控制 API （5309）、界面（80/443）、ssh （2222）和 WireGuard 的 UDP 端口，从宿主机的局域网地址中继进客户机—— 正是这一点让运行 Android 客户端的手机能够访问虚拟机。 设置 VM_LAN=0 可关闭这些中继。

从实体 U 盘启动（qemu-usb）

make qemu-usb USB_DEV=/dev/sdX

直接从已写好的实体 U 盘（而非构建出的镜像）在前台启动 QEMU—— 很适合用来确认刚写好的 U 盘确实能启动。设备以只读方式打开（快照模式）， 因此客户机的写入都会被丢弃，真实 U 盘绝不会被修改；四块虚拟数据盘仍会挂载以便测试存储。 这个目标不构建任何东西——请先克隆 install 仓库，用 install.sh 或 make flash 写一个 U 盘，然后把 USB_DEV 指向它。 在 x86_64 宿主机上，TARGET=aarch64（或 rpi）会以全系统模拟 方式启动该 U 盘，因此没有对应硬件也能测试异架构镜像。

停止与清理

# 停止虚拟机
make stop

# 停止虚拟机并删除镜像和虚拟磁盘
make clean

环境变量

串口控制台

# 连接到虚拟机的串口控制台
make serial

# 或者手动通过 socat 连接
socat -,rawer,escape=0x1d unix-connect:/tmp/town-os-serial.sock

# 用 Ctrl-] 断开

找到虚拟机

# 获取虚拟机的 IP 地址
make vm-ip

# 或者从宿主机通过 mDNS 连接
ssh root@town-os.local

RAID 安装

磁盘配置由 ttyforce 在首次启动时交互式地完成。所有存储都使用 btrfs。

自动选择 RAID 级别

ttyforce 会检测可用磁盘，按传输类型（NVMe、SATA 等）和相近容量分组， 然后根据磁盘数量自动选择 RAID 级别：

• 1 块盘——single 模式（无冗余）
• 2 块盘——RAID 1（btrfs 镜像）
• 3 块及以上——RAID 5（btrfs 带校验的条带）

默认挂载点是 /town-os。ttyforce 会创建 @etc 和 @var 子卷，以配合 overlayfs 实现持久化。

磁盘检测

ttyforce 会自动检测可用的存储设备。它能识别 NVMe 硬盘、SATA/SAS 硬盘和 SD 卡， 同时排除启动用的 USB 设备以及任何可移动介质。这套检测逻辑确保 Town OS 绝不会碰它自己启动所用的那块盘。

叠加文件系统

无论使用哪种存储后端，Town OS 都通过 overlay 挂载来持久化 /var 和 /etc。下层来自 squashfs 根文件系统， 上层则位于 RAID/ZFS 存储上。这样一来，系统配置和服务数据能跨重启保留， 而基础操作系统始终保持不可变。

托管静态网站

除了容器化的软件包，Town OS 还内置了静态网站托管， 它始终在线，并在 仪表盘 → 页面 中管理。每个页面都由入口后的 一个共享 Web 服务器提供服务，并像软件包一样，在其 网络的 TLD 下获得 DNS 名称和 TLS 证书。

内容来源

创建页面时，你需要选定一个名称、一个域名 （默认与名称相同）、一个网络（默认为 home）， 以及三种内容来源之一：

• 上传归档——上传你网站的 tar 包。在你上传归档之前，页面会保持待处理状态。
• Git 仓库——从仓库 URL 克隆。你可以指定分支（默认为 main），这对发布在 gh-pages 上的站点很方便。
• 容器镜像——从 OCI 镜像中提取某个目录。

git 和容器类型的页面是异步准备的——表格中会显示 准备中… 标记，最终变为「活动」或「错误」。对 git 和容器页面， 用重新构建拉取最新内容；对归档页面，则改为上传新的 tar 包。

页面是如何提供服务的

每个页面都位于自己的存储子卷上，并直接通过 80 端口以 HTTP 提供服务， 而软件包服务则会把 80 端口重定向到 HTTPS。由于页面同样归属某个网络， 它的名称会在该网络的 TLD 下解析，可从你的局域网访问；如果该网络是 WireGuard 覆盖网，你已登记的远程设备也能访问。

制作软件包

Town OS 的软件包是描述如何运行容器化服务的 YAML 文件。 完整规范请参阅打包格式参考文档。 本节讲的是实际的工作流程。

仓库结构

软件包仓库就是一个带有 packages/ 目录的 git 仓库。 每个软件包各占一个子目录，其中存放带版本号的 YAML 定义：

my-packages/
  packages/
    my-app/
      1.0.yaml
      2.0.yaml

编写软件包定义

一个最小的软件包只需要 image 字段。典型的软件包还会包含描述、 网络、卷和面向用户的提问：

image: myapp:latest
description: My custom application
supplies: ["http"]
network:
  external:
    "@port@": "8080"
volumes:
  data:
    mountpoint: /app/data
    quota: 5gb
questions:
  port:
    query: "What external port should this app use?"
    type: port
    default: "9000"
notes:
  URL:
    value: "http://@LOCAL_EXTERNAL_HOST@:@port@"
    type: url

除了自由文本和 port，提问还支持几种类型：secret （留空时自动生成）、boolean（渲染为复选框）、 oauth（一个连接按钮，会走服务商的设备流来获取令牌）， 而且任何提问都可以标记为 optional: true 以允许留空。 完整列表见打包格式参考中的提问一节。 安装时，操作者还会选择该软件包在哪个网络上提供服务。

模板系统

使用 @variable@ 语法来引用提问的回答和内置变量 （@LOCAL_EXTERNAL_HOST@、@LOCAL_INTERNAL_HOST@）。 模板可用于环境变量、端口映射、配额和说明项的取值中。

本地测试

用开发环境来测试你的软件包。 把仓库放在磁盘上，通过界面或 repositories.json 添加它， 然后安装你的软件包。开发环境提供了完整的 Town OS 栈以供测试。

添加仓库

可以通过界面（软件包 → 仓库 → 添加仓库）把你的软件包仓库 添加到 Town OS，也可以直接编辑 repositories.json：

[
  {"name": "default", "url": "https://github.com/town-os/default-packages"},
  {"name": "my-packages", "url": "https://github.com/myuser/my-packages"}
]

开发环境与测试套件

Town OS 的开发环境使用 Podman 容器在本地运行完整的技术栈。 这是测试改动、开发软件包和运行测试套件最快的方式。

先决条件

• Linux——btrfs 和 Podman 的 rootful 容器需要它
• Podman——容器运行时（rootful 模式，需要 sudo）
• Go 1.25+——用于后端 API 服务器
• Bun——用于前端构建和开发服务器
• btrfs-progs——用于存储管理
• QEMU——qemu-system-x86_64 与 qemu-img，用于支持虚拟机软件包
• libsystemd——用于 systemd 集成的开发头文件
• golangci-lint——用于 Go 代码检查
• Python 3——用于构建和测试脚本

启动开发环境

git clone https://gitea.com/town-os/town-os.git
cd town-os
make dev

这会启动带热重载的完整开发栈。就绪之后， 打开终端里输出的网址即可访问 Town OS 仪表盘。

开发环境命令

运行测试

集成测试

集成测试在一个特权 Podman 容器中运行，该容器提供真实的 btrfs 文件系统、 systemd，以及 Podman-in-Podman。这确保测试走的是与生产环境相同的代码路径。 测试容器是一次性的——每次测试都会新建，结束后清理掉。