設定

這一章說明自架版的各項設定：寫在哪裡、每一項的作用、資料庫，以及怎麼備份整個系統。安裝方式見〈安裝〉章。

config.toml 或環境變數

每一項設定都可以寫在 config.toml（放在 server 旁邊，或掛進 container），也可以用環境變數設定。兩者可以並用：環境變數永遠優先，config.toml 只補上還沒設定的項目。依你的環境挑一種即可。

只認得下表列出的項目。打錯字或多出不認得的區塊時，系統會在啟動時停下並指出是哪一項，不會默默忽略。

設定項目

項目	環境變數	預設值	作用
`database.mode`	`DATABASE_MODE`	—	`"embedded"` 代表由系統自己帶一份 PostgreSQL 16（內嵌資料庫模式）。不能跟 `database.url` 同時設定。
`database.embedded_data_dir`	`DATABASE_EMBEDDED_DATA_DIR`	`data`	內嵌資料庫存放檔案的位置，相對於執行 `server` 的目錄。
`database.url`	`DATABASE_URL`	—	外部 PostgreSQL 16 以上資料庫的連線字串。不能跟 `database.mode` 同時設定。
`database.max_connections`	`DATABASE_MAX_CONNECTIONS`	`5`	資料庫連線數上限。
`server.ip`	`IP`	`127.0.0.1`	監聽的位址。要讓其他機器連進來時用 `0.0.0.0`；tarball 附的 `Dockerfile` 已經這樣設定。
`server.port`	`PORT`	`8080`	監聽的連接埠。
`server.public_url`	`PUBLIC_URL`	`http://127.0.0.1:8899`	大家連到這個系統用的網址（含連接埠），會用在連結與信件裡。
`server.secure_cookies`	`SECURE_COOKIES`	`false`	只在 HTTPS 下送出 cookie。前面有反向代理提供 HTTPS 時開啟。
`server.update_check_enabled`	`UPDATE_CHECK_ENABLED`	`true`	每天檢查一次有沒有新版本，有的話在頁面上方提示。見下方「檢查新版本」。
`server.default_language`	`DEFAULT_LANGUAGE`	`zh-TW`	`zh-TW` 或 `en`。瀏覽器沒有送出可辨識的語言時使用的顯示語言，以及查不到使用者設定時寄信用的語言。
`mail.smtp_url`	`SMTP_URL`	—	寄送註冊確認、重設密碼與邀請信用的 SMTP 伺服器。沒設定就是無信件模式。用 `smtps://` 開頭即啟用 TLS。
`mail.from`	`MAIL_FROM`	`KakePhooa <no-reply@localhost>`	這些信的寄件者，例如 `KakePhooa <[email protected]>`。
`mail.smtp_username`	`SMTP_USERNAME`	—	SMTP 帳號（伺服器需要時）。
`mail.smtp_password`	`SMTP_PASSWORD`	—	SMTP 密碼（伺服器需要時）。
`auth.signup_policy`	`SIGNUP_POLICY`	`closed`	`closed` 不接受新的註冊；`open` 任何人都能註冊。第一個帳號一定會通過。
`sso.google.enabled`	`GOOGLE_LOGIN_ENABLED`	`true`	下面兩項都有設定時，提供「使用 Google 帳戶登入」。
`sso.google.client_id`	`GOOGLE_CLIENT_ID`	—	Google OAuth client ID。
`sso.google.client_secret`	`GOOGLE_CLIENT_SECRET`	—	Google OAuth client secret。

不論 signup_policy 怎麼設，自架版部署只支援一個帳號（見〈安裝〉章的「你的帳號」），所以通常設成 closed。

檢查新版本

系統每天向 https://kakephooa.com/releases/self-hosted/latest.json 取一次最新版本資訊。有比目前更新的版本時，登入後的頁面上方會顯示新版本的重點與發行頁面的連結；按「這個版本不再提示」後，這個瀏覽器不再顯示同一個版本。

這個請求不帶任何你的資料，只是讀取一份公開的檔案。連不到（例如機器沒有對外網路）時不會顯示任何東西，其他功能照常運作。不想檢查時，把 server.update_check_enabled 設成 false。

無信件模式

沒有設定 mail.smtp_url 時，系統以無信件模式運作：註冊不寄確認信、直接登入；「忘記密碼」沒辦法寄連結，請改用 server set-password（見〈安裝〉章）。

使用外部資料庫

想接你已經在用的 PostgreSQL 16 以上資料庫，修改 config.toml 的 [database] 區塊：把 mode = "embedded" 註解掉，並把 url 設成你的連線字串。mode 與 url 互斥：兩者都設、或兩者都沒設，系統都會拒絕啟動，不會默默挑一個用。用 Docker Compose 另外跑一個 PostgreSQL container 的完整範例，見〈安裝〉章的「Docker Compose 範例」。

內嵌資料庫的資料目錄

內嵌資料庫模式下，資料放在 database.embedded_data_dir（預設 data；container 裡是 /app/data，也就是 docker-compose.yml 的 data volume）。這個目錄裡有 PostgreSQL 的資料檔（在 pgdata/）與一組隨機產生的資料庫密碼（只有擁有者能讀的檔案），第一次啟動時產生，之後沿用。

資料目錄必須放在支援 Linux 檔案權限的本機檔案系統上，因為 PostgreSQL 要求只有它的擁有者能存取這個目錄。Windows 磁碟（例如在 WSL 裡的 /mnt/c）與網路磁碟（SMB、NFS）做不到這一點，系統啟動時會先檢查並拒絕，這時請把 database.embedded_data_dir 改到本機 Linux 檔案系統上。Windows 版在 Windows 本機磁碟上執行，不受這個限制。

PostgreSQL 的主版本固定是 16。如果資料目錄是別的主版本建立的，系統會停下並回報錯誤，不會重新初始化——重新初始化會把資料丟掉。請還原一份相容的備份，或把 database.url 指向那份資料真正所在的地方。

備份整個資料庫

整個資料庫的備份與介面裡的備份是兩回事：

整個資料庫的備份讓一切回到某個時間點。升級出問題、或要重建整台機器時靠的是它。內嵌資料庫模式下，備份整個資料目錄；Docker／Podman 例如 docker run --rm -v kakephooa_data:/data -v $(pwd):/backup alpine tar czf /backup/data-backup.tar.gz -C /data .（kakephooa_data 是附的 docker-compose.yml 的 volume；改過 compose 專案時照著調整）。使用外部資料庫時，照常用 pg_dump 與 pg_restore。
介面裡的備份（家計的「設定」→「匯出」）是單一家計的資料。還原一律建立一個新的家計（見〈備份〉章），適合搬到另一台伺服器或留一份可攜的複本，但不是升級失敗時的退路。

升級前一定要先備份整個資料庫，平常也定期用介面裡的備份留一份可攜的複本。要多久做一次、留幾份、放在哪裡，由你決定。