安裝

這一章給自己架設 KakePhooa（自架版）的人：從下載到第一次登入，以及升級與救援。各項設定見〈設定〉章。

自架版供單人免費使用，不設期限。

支援範圍

由一個人維護，回覆速度會比較慢。不在支援範圍內：你自己的 Docker／Podman 環境、反向代理、TLS 憑證、網域設定、資料庫調校，這些都屬於自架環境的一部分。

軟體本身的問題（照著步驟做仍然跑不起來，或某個功能跟這份使用手冊描述不符）歡迎回報，請附上版本號（見下方「版本」）。

系統需求

一台 64 位元的 Linux 機器（實體機、VM、雲端 VPS、NAS、樹莓派都可以）：x86_64（linux/amd64）用 linux-x86_64 的 tarball，ARM 64 位元（linux/arm64，例如樹莓派 3 以後的機型搭配 64 位元系統）用 linux-aarch64 的 tarball。或一台 64 位元 x86 的 Windows 電腦（Windows 版）。不支援 32 位元系統。
Linux 上：直接執行 tarball 裡的執行檔，或在 Docker 或 Podman（含 compose）裡跑現成的 container image。Windows 上：執行 zip 裡的執行檔。在 Windows 與 Linux 桌面（GNOME、XFCE）上也可以縮到系統匣常駐執行（見「以系統匣常駐」）。macOS 上：用 Docker Desktop 跑同一個 image（見「用 Docker 或 Podman 安裝」），沒有原生 macOS 版本。
資料庫不需要另外安裝：系統預設自己帶一份 PostgreSQL 16（內嵌資料庫模式）。想接你已經在用的資料庫，見〈設定〉章的「使用外部資料庫」。
直接執行 Linux tarball 時，不需要另外安裝函式庫，內建 PostgreSQL 用到的函式庫都已經包在執行檔裡。系統要是 Debian 12、Ubuntu 22.04 或更新的版本（glibc 2.34 以上），並且裝有時區資料（tzdata 套件）。一般安裝的系統都有時區資料，只有精簡的 container base image 可能沒有；缺少時，啟動會出現 invalid value for parameter "TimeZone"，用 sudo apt install tzdata 補上即可。

以系統匣常駐

不想一直開著終端機或主控台視窗時，改用 tarball 與 zip 裡附的 kakephooa-tray（Windows 為 kakephooa-tray.exe）啟動。它在背景啟動系統、在系統匣放一個圖示，並用預設瀏覽器開啟。關掉瀏覽器不會停止系統。

支援 Windows，以及 Linux 的 GNOME 與 XFCE 桌面。

依「用 Linux tarball 安裝」或「在 Windows 上安裝」的第 1 步下載、驗證並解壓縮。
在解壓縮的目錄裡點兩下 kakephooa-tray（Windows 為 kakephooa-tray.exe）。目錄裡還沒有 config.toml 時，它會先把 config.toml.example 複製成 config.toml：使用內嵌資料庫，只接受這台電腦的連線。要改設定的話，照〈設定〉章修改這份檔案，再從選單按「重新啟動」。
瀏覽器會先開啟「正在啟動」頁面，系統就緒後自動轉到登入頁面。第一次啟動要建立資料庫，頁面會顯示「正在建立資料庫」，需要的時間比平常長，視電腦速度而定。等太久時頁面會提示你從系統匣選單「檢視記錄檔」查看原因。

用左鍵點圖示會開啟系統。右鍵選單：

項目	作用
狀態	啟動中、執行中、已停止或啟動失敗
版本	目前執行的版本
複製網址	子選單列出可複製的網址，點了複製到剪貼簿，方便貼到手機或其他裝置：「本機」（`public_url`；設成網域或 Tailscale 網址時顯示為「公開網址」）、「區網」（勾選「允許手機連線」後出現）、「Tailscale」（這台電腦有安裝並登入 Tailscale，且手機連得到時出現）
開啟	用預設瀏覽器開啟系統
以手機連線	開啟一個頁面，顯示手機要開的網址與它的 QR code，見下方「用手機連線」
檢視記錄檔	開啟 `logs/server.log`，系統的訊息都寫在這裡
允許手機連線	勾選後，同一個網路上的其他裝置也能連到系統，見下方「用手機連線」
開機時自動啟動	勾選後，登入電腦時自動啟動。自動啟動時只常駐在系統匣，不開啟瀏覽器
重新啟動	停止後再啟動系統，例如改完 `config.toml` 之後
結束	停止系統並移除圖示

kakephooa-tray 與 ./server、start.bat 擇一使用，不要同時啟動：後啟動的那個會因為資料庫或連接埠已被佔用而失敗。重複點兩下 kakephooa-tray 不會啟動第二份，只會開啟瀏覽器。
狀態變成「啟動失敗」或「已停止」時，打開記錄檔看最後幾行。系統不會自動重新啟動，修正問題後按「重新啟動」。
「開機時自動啟動」記住的是這個資料夾的位置。資料夾搬家或改用新版本的目錄後，選單會顯示未勾選，在新的位置重新勾選一次即可。
Windows 第一次執行時可能出現「Windows 已保護您的電腦」，按「其他資訊」再按「仍要執行」。防毒軟體攔下 kakephooa-tray.exe 時，先照下方「驗證發行版」確認檔案，再把它加入允許清單。
Linux 的 GNOME：Ubuntu 可以直接使用。Fedora、Debian 等沒有預裝系統匣支援的發行版，要先安裝 GNOME 擴充套件「AppIndicator and KStatusNotifierItem Support」。沒有系統匣時系統照樣會啟動並開啟瀏覽器，只是沒有圖示；要停止時結束 kakephooa-tray（例如在終端機按 Ctrl+C）。

用手機連線

系統預設只接受這台電腦的連線，手機連不進來。

在選單勾選「允許手機連線」。它會把 config.toml 的 [server] ip 改成 0.0.0.0 並重新啟動系統，就緒後自動開啟「以手機連線」頁面。取消勾選會改回 127.0.0.1。
手機連到跟這台電腦同一個網路（例如家裡的 Wi-Fi），掃描頁面上的 QR code。頁面依瀏覽器的語言顯示，右上角可切換「中文」與「English」。
Windows 防火牆詢問是否允許 server.exe 存取網路時，選擇允許。

勾選之前，先在這台電腦上註冊你的帳號：系統還沒有任何帳號時，同一個網路上第一個註冊的人會成為這套系統的使用者。

這樣連線用的是 http，可以登入、記帳、查看預算，但不能加到主畫面、離線記帳或使用 Passkey。需要這些功能時，照〈從手機連線〉章改用 HTTPS 網址；public_url 改成 HTTPS 網址之後，「以手機連線」頁面顯示的就是那個網址。

這台電腦有安裝並登入 Tailscale 時，頁面還會多顯示一個 Tailscale 網址：手機開啟 Tailscale 後，不在同一個網路也能連線。照〈從手機連線〉章設定 tailscale serve 後，頁面只顯示它的 HTTPS 網址，這時不需要勾選「允許手機連線」。沒有安裝 Tailscale 不影響系統啟動。

用環境變數（包括 .env）設定 IP 時，環境變數優先，「允許手機連線」無法點選。

用 Docker 或 Podman 安裝

現成的 image 是 ghcr.io/single9/kakephooa，支援 linux/amd64 與 linux/arm64，內容就是 Linux tarball 裡的執行檔。NAS 的 Container Manager（Synology）、Container Station（QNAP）也可以直接拉這個 image。下面的 compose 與設定是起點，不保證在每個環境都能直接用；調整成適合你機器的樣子是自架的一部分。

建立一個目錄（例如 kakephooa），在裡面建立 config.toml，public_url 改成這台機器實際被連到的網址：
```
[database]
mode = "embedded"

[server]
public_url = "http://192.168.1.10:8080"
```
首次啟動前須先建立 config.toml：檔案不存在時，Docker 會建立同名的目錄，container 會以 Is a directory 失敗。補救方式是刪除該目錄、建立檔案，並先執行 docker compose down 再重新啟動。所有設定項目見 Linux tarball 裡的 config.toml.example 與〈設定〉章。
在同一個目錄建立 docker-compose.yml（見下方「Docker Compose 範例」的「內嵌資料庫」），1.1.1 換成要安裝的版本（見發行頁面）。
啟動：docker compose up -d（或 podman-compose up -d）。
等幾秒讓資料庫遷移跑完，然後開啟 http://<這台機器的位址>:8080。
照一般註冊流程建立你的帳號（見下方「你的帳號」）。

config.toml 的權限

container 以非 root 使用者執行，config.toml 必須是其他使用者也能讀取的檔案。讀不到時，container 會不斷重新啟動，log 出現 config.toml 讀取失敗：Permission denied (os error 13)。在這台機器上執行：

chmod 644 config.toml

Synology 等 NAS 會讓共用資料夾裡新建或複製的檔案繼承資料夾的 ACL，只開放給特定帳號，container 裡的使用者因此讀不到。以 SSH 登入 NAS，在 config.toml 所在的目錄執行上面這行，會改回一般的檔案權限。

自行建立 image

不想使用現成的 image 時，Linux tarball 裡附有 Dockerfile 與 docker-compose.yml，在你自己的機器上把 tarball 裡的執行檔包成 image，不需要編譯。在 tarball 解壓縮出來的目錄把 config.toml.example 複製成 config.toml，再執行 docker compose up -d --build。不用 compose 時，執行 docker build -t kakephooa:<version> . 建立 image。Dockerfile 只做這幾件事：以 debian:bookworm-slim 為基礎，裝上 ca-certificates、tzdata、wget，把 server 與 public/ 複製到 /app，以非 root 使用者執行，監聽 0.0.0.0:8080。要換 base image 或調整內容，照著改即可。建立 image 時須連網下載套件；container 連不上網路的環境（部分 NAS 即是如此）請改用現成的 image。

macOS 上請安裝 Docker Desktop，步驟相同，Docker 會依 Mac 的架構拉取對應的 image。

反向代理與 TLS 不在這份 compose 裡。只在電腦上使用時不需要 TLS；手機要加到主畫面、離線記帳或使用 Passkey 時，網址必須是 HTTPS 網域，設定方式見〈從手機連線〉章。

Docker Compose 範例

下面兩個範例都可以直接當起點，差別只在資料庫放在哪裡。兩個檔案放在同一個目錄，1.1.1 換成要安裝的版本，把 public_url 改成這台機器實際被連到的網址，再執行 docker compose up -d。

name: kakephooa 固定 compose 的專案名稱。目錄改名或搬到別處後再啟動，volume 還是原本那一個（例如 kakephooa_data），資料不會留在舊目錄的專案底下。

內嵌資料庫（預設）

資料庫跟系統在同一個 container 裡，資料存在 data volume。tarball 附的 docker-compose.yml 就是這種設定。

docker-compose.yml：

name: kakephooa

services:
  app:
    image: ghcr.io/single9/kakephooa:1.1.1
    restart: unless-stopped
    volumes:
      - ./config.toml:/app/config.toml:ro
      - data:/app/data
    ports:
      - "8080:8080"

volumes:
  data:

config.toml：

[database]
mode = "embedded"

[server]
public_url = "http://192.168.1.10:8080"

備份時備份 data volume（見〈設定〉章的「備份整個資料庫」）。

外部資料庫

資料庫另外跑在一個 PostgreSQL container 裡。適合想自己管理 PostgreSQL 的人，例如用自己習慣的工具備份或調整設定。

docker-compose.yml：

name: kakephooa

services:
  app:
    image: ghcr.io/single9/kakephooa:1.1.1
    restart: unless-stopped
    volumes:
      - ./config.toml:/app/config.toml:ro
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: kakephooa
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: kakephooa
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U kakephooa -d kakephooa"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  pgdata:

config.toml：

[database]
url = "postgres://kakephooa:change-me@db:5432/kakephooa"

[server]
public_url = "http://192.168.1.10:8080"

把兩個檔案裡的 change-me 換成同一組你自己的密碼。
config.toml 裡不要再寫 mode = "embedded"，mode 與 url 只能設一個（見〈設定〉章的「使用外部資料庫」）。
db 沒有把連接埠開到主機上，只有同一份 compose 裡的 app 連得到。
healthcheck 的 -h 127.0.0.1 不要拿掉：PostgreSQL 第一次初始化時會先起一個只接受本機 socket 連線的暫時伺服器，不帶 -h 的 pg_isready 會提早回報就緒，app 就會在資料庫真正啟動前連線失敗。

備份整個資料庫用 pg_dump：

docker compose exec -T db pg_dump -U kakephooa -d kakephooa --format=custom > kakephooa.dump

用 Linux tarball 安裝

從發行頁面下載符合機器架構的 tarball（kakephooa-<version>-linux-<arch>.tar.gz，<arch> 是 x86_64 或 aarch64；不確定時執行 uname -m 查看），連同 SHA256SUMS 與 SHA256SUMS.asc，先驗證（見下方「驗證發行版」）再解壓縮：
```
tar xzf kakephooa-<version>-linux-<arch>.tar.gz
cd kakephooa-<version>-linux-<arch>
```
目錄結構固定：server、kakephooa-tray、public/、config.toml.example、LICENSE、README-install.md、README-install.en.md、THIRD-PARTY-NOTICES.md。server 會在你執行它的目錄下找 public/，不要動內部結構。
把 config.toml.example 複製成 config.toml，設定 public_url（也可以改用環境變數，見〈設定〉章）。
啟動：
```
./server
```
第一次啟動會跑資料庫遷移。內嵌資料庫放在執行 server 的目錄下的 data/，這個目錄要在本機的 Linux 檔案系統上，不能是 Windows 磁碟或網路磁碟（見〈設定〉章的「內嵌資料庫的資料目錄」）。

在 Windows 上安裝

從發行頁面下載 kakephooa-<version>-windows-x86_64.zip，連同 SHA256SUMS 與 SHA256SUMS.asc，驗證後解壓縮。目錄結構跟 Linux tarball 相同，只是 server 換成 server.exe。
把 config.toml.example 複製成 config.toml，設定 public_url。
在解壓縮的資料夾雙擊 start.bat。server.exe 結束後視窗會保持開啟，錯誤訊息可完整閱讀。改用 PowerShell 啟動時：
```
.\server.exe
```
第一次執行時，Windows 防火牆可能會詢問是否允許 server.exe 使用網路；需要讓其他裝置連進來就允許。內嵌資料庫放在執行目錄下的 data\。這一章寫 ./server 的地方，在 Windows 上都改用 .\server.exe。

驗證發行版

每個 tarball 與 zip 都附有 SHA256SUMS（校驗碼）與 SHA256SUMS.asc（維護者的 GPG 簽章），讓你確認下載到的檔案沒有損毀，也確實是這個專案發布的。

發行版簽章金鑰：

KakePhooa Releases <[email protected]>
Fingerprint: ACC6 7AF4 2A28 A134 C82C  9A1A E27C A53B 662A 823F

公鑰跟發行檔案放在一起，檔名是 kakephooa-release-signing-pubkey.asc。匯入後驗證：

gpg --import kakephooa-release-signing-pubkey.asc
gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

Windows 上沒有 sha256sum 時，在 PowerShell 執行 Get-FileHash kakephooa-<version>-windows-x86_64.zip，把結果跟 SHA256SUMS 裡對應的那一行比對（gpg --verify 用 Gpg4win 一樣可以做）。

第一次會看到 gpg: WARNING: This key is not certified with a trusted signature，這是正常的，只代表你匯入了金鑰、還沒認證它。重點是輸出裡有 Good signature from "KakePhooa Releases <[email protected]>"，而且指紋跟上面一致。

你的帳號

照一般的註冊頁面註冊。系統裡還沒有任何帳號時，第一次註冊一定會通過，不論 signup_policy 怎麼設。這就是你的帳號，也是自架版部署唯一支援的帳號：之後的註冊一律會被拒絕。

授權條款（LICENSE 第四條）不允許把這套軟體架成讓你的家庭或組織以外的人註冊使用的服務。有這個需要的話，請寄信到 [email protected]。

版本

帳號設定頁最下方會顯示目前的版本（v<x.y.z>）。回報問題時請附上這個版本號。

忘記密碼（無信件模式）

自架版預設不寄信（無信件模式），所以「忘記密碼」沒辦法寄連結給你。請改用內建的指令直接設定新密碼：

# Docker／Podman：
docker compose exec app ./server set-password [email protected]

# tarball：
./server set-password [email protected]

密碼從標準輸入讀取，輸入時不會顯示。設定完成後，這個帳號原本所有登入中的 session 都會被登出，請用新密碼重新登入。

關閉某個帳號的兩步驟驗證

帳號開了兩步驟驗證，又同時遺失驗證器 app、Passkey 與復原碼時，可以用內建的指令替它關閉：

# Docker／Podman：
docker compose exec app ./server reset-mfa [email protected]

# tarball：
./server reset-mfa [email protected]

這會拿掉這個帳號的驗證器 app 與所有 Passkey、作廢所有復原碼，並登出它所有登入中的 session。之後用密碼就能登入，請本人登入後重新開啟兩步驟驗證。找不到這個 email 的帳號時，指令以狀態碼 1 結束。

升級

有新版本時，登入後的頁面上方會出現提示（見〈設定〉章的「檢查新版本」）。

先備份整個資料庫（見〈設定〉章的「備份整個資料庫」）。
從發行頁面下載新版本的 tarball 或 zip 並重新啟動。Docker／Podman：把 docker-compose.yml 裡 image 的版本號改成新版本，再執行 docker compose up -d。自行建立 image 時，把 config.toml 複製到新版本解壓縮出來的目錄，在那裡執行 docker compose up -d --build。資料庫遷移會在啟動時自動執行。用 kakephooa-tray 啟動的話，先從選單按「結束」，在新版本的目錄啟動後，重新勾選「開機時自動啟動」。
不支援降版。 新版本寫進資料庫的內容不保證能被舊版讀懂。升級前的備份就是你的退路。

健康檢查

GET /healthz 回報資料庫是否連得上。docker-compose.yml 的 healthcheck 用的就是它，你自己的監控系統也可以直接呼叫。

使用統計

帳號設定頁的「使用統計」顯示這個部署每天的使用次數：

首頁瀏覽：開啟首頁的次數。
網頁記帳：在網頁上新增 Expense 的筆數，離線時記下、之後同步上來的也算在內。

可以切換最近 7、30、90 天，「每日明細」列出每一天的數字。日期以 UTC 計算，所以在台灣是每天早上 8 點換日。

這些數字只存在你自己的資料庫裡，只記次數、不記是誰，也不會傳送到任何地方。