使用者指南

從原始碼建置 USB 映像檔

Town OS 的 USB 映像檔由 install 儲存庫建置。建置流程會產生一個可開機的映像檔，根檔案系統為 squashfs，分割配置為 GPT。

先決條件

你需要一台 Linux 主機和一支隨身碟（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 即可建置完整的 USB 映像檔。 這個流程會下載基礎系統、安裝 Town OS 元件、把所有內容壓縮成 squashfs 檔案系統， 並組出帶 GPT 分割表的最終磁碟映像檔。

分割與 squashfs

產生的映像檔採用 GPT 配置，包含：

• 一個 BIOS 開機分割區（1 MiB），供傳統 BIOS 開機使用
• 一個 EFI 系統分割區（64 MiB，FAT32），供 UEFI 開機使用
• 一個資料分割區（ext4），存放 squashfs 根檔案系統與 GRUB

開機時，Town OS 會把 squashfs 掛載為唯讀的下層，並在其上疊一層 tmpfs。 這表示作業系統完全在記憶體中執行——隨身碟本身只在開機時被讀取。 所有執行期的變更都發生在記憶體裡，重新開機後即被丟棄，每次都給你一塊乾淨的白板。

寫入映像檔

最簡單的方式是 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。這項設定通常在 LAN 設定、DHCP 或 位址保留 之下。 在用戶端清單中找到 Town OS 機器，把它目前的 IP 保留下來即可。

如果你的路由器不支援 DHCP 保留，也可以在 town-os.yaml 中加上設定， 直接在 Town OS 機器上設定固定 IP。

在路由器中變更 DNS 伺服器

各廠牌路由器的步驟略有不同，但大方向都一樣：

1. 登入路由器的管理介面（通常是 192.168.1.1 或 192.168.0.1）
2. 找到 DHCP 設定、LAN 設定 或 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 → 服務 中，你可以逐一切換服務是否發布—— 未發布的服務照常執行，只是不再能以名稱解析。每個服務的完整名稱遵循 <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 對等點 TTL 調整），必須更新才能維持連線；被棄用的裝置會自動過期。由管理者新增的對等點則是永久的。

觀察與中斷對等點

網路頁面上的已連線對等點面板，會列出所有網路中每一個已登錄的對等點， 並顯示即時交握狀態、疊加網 IP、傳輸量與到期時間。若要強制切斷某台裝置， 請使用中斷連線——它會移除該對等點、立即拆掉通道並撤銷其金鑰， 因此該裝置在重新登錄之前都無法再連上來。

在指定網路上安裝套件

安裝對話框（以及頁面對話框）中有一個網路選擇器。 你選的網路決定該服務的 DNS 名稱與 TLS 憑證——安裝在 office 上的套件會在 .office 下解析，憑證也依該名稱簽發。非預設網路上的服務是雙棲的： 對通道對等點解析為疊加網位址，對本地用戶端則解析為區域網路位址。把套件重新安裝到 另一個網路，會把它的 DNS 與憑證一併移到該網路的 TLD 下。

舉例來說，把 Jitsi 安裝在 TLD 為 fart 的網路上，它會發布在 jitsi.default.fart。跑起來之後，該服務會以可點擊的連結出現在你的 儀表板上，網路上的任何裝置都能直接打開。

用 USB 映像檔建立虛擬機器

install 儲存庫包含在虛擬機器中啟動 Town OS 的指令稿，這在測試與開發時很有用—— 可以用你從原始碼建置的映像檔，也可以直接用 已經燒好的實體隨身碟。 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 可關閉這些轉送。

從實體 USB 開機（qemu-usb）

make qemu-usb USB_DEV=/dev/sdX

直接從燒好的實體隨身碟（而非建置出的映像檔）在前景啟動 QEMU—— 很適合用來確認剛燒好的隨身碟真的能開機。裝置以唯讀方式開啟（快照模式）， 因此客體機的寫入都會被丟棄，真正的隨身碟絕不會被更動；四顆虛擬資料磁碟仍會掛上供測試儲存。 這個目標不會建置任何東西——請先複製 install 儲存庫，用 install.sh 或 make flash 燒一支隨身碟，再把 USB_DEV 指向它。 在 x86_64 主機上，TARGET=aarch64（或 rpi）會以全系統模擬 方式開機該隨身碟，因此沒有對應硬體也能測試異架構的映像檔。

停止與清理

# 停止虛擬機器
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 還內建靜態網站代管， 它始終開著，並在 儀表板 → 頁面 中管理。每個頁面都由入口後方的 一個共用網頁伺服器提供服務，並像套件一樣，在其 網路的 TLD 下取得 DNS 名稱與 TLS 憑證。

內容來源

建立頁面時，你要挑選一個名稱、一個網域 （預設與名稱相同）、一個網路（預設為 home）， 以及三種內容來源之一：

• 上傳封存檔——上傳你網站的 tarball。在你上傳封存檔之前，頁面會維持待處理狀態。
• Git 儲存庫——從儲存庫網址複製。你可以指定分支（預設為 main），這對發布在 gh-pages 的網站很方便。
• 容器映像檔——從 OCI 映像檔中擷取某個目錄。

git 與容器頁面採非同步佈建——表格中會顯示 佈建中… 標記，最後會變成使用中或錯誤。對 git 與容器頁面， 請用重新建置拉取最新內容；至於封存檔頁面，則改為上傳新的 tarball。

頁面是怎麼提供服務的

每個頁面都位於自己的儲存子磁碟區上，並直接以 HTTP 於 80 連接埠提供服務， 而套件服務則會把 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。這確保測試走的是與正式安裝相同的程式碼路徑。 測試容器是用完即丟的——每次測試都會重新建立，結束後再清理掉。