從手機連線

這一章說明怎麼讓手機連到你自架的系統，以及要用到完整功能需要哪些條件。安裝方式見〈安裝〉章，各項設定見〈設定〉章。

這一章的 Tailscale、DDNS 與 Traefik 都是範例，跟〈安裝〉章的 Docker Compose 範例一樣是起點。反向代理、TLS 憑證與網域設定屬於自架環境的一部分，不在支援範圍內（見〈安裝〉章的「支援範圍」）。

用 http 連線時能做什麼

手機跟系統在同一個網路裡時，直接開 http://<這台機器的位址>:8080（例如 http://192.168.1.10:8080）就能連上。直接執行 tarball 或 zip 時，系統預設只接受本機連線，要先在 config.toml 的 [server] 設定 ip = "0.0.0.0" 再重新啟動；用 kakephooa-tray 啟動時，勾選選單的「允許手機連線」即可（見〈安裝〉章的「用手機連線」）。這樣連線時可以登入、記帳、查看預算，但瀏覽器只在 HTTPS 網域（或 localhost）上開放以下功能，所以這些都不能用：

加到主畫面，像 app 一樣開啟。
離線記帳（見〈記帳〉章的「離線」）。
Passkey（見〈帳號〉章）。

要用到這些功能，手機連線的網址必須是 HTTPS 網域。下面兩種方式擇一即可：

方式	適合	需要
Tailscale	只有自己的裝置要連，不想讓系統出現在網際網路上	手機與這台機器都裝 Tailscale
DDNS 與 Traefik	手機不想裝額外的 app，或不在家時也要直接連	一個網域、路由器可設定連接埠轉送、對外 IP 不是共用的

兩種方式設定完成後，都要照下方「調整 config.toml」修改設定。

用 Tailscale

Tailscale 會在你的裝置之間建立一個私人網路，並替這台機器發一張 *.ts.net 網域的 HTTPS 憑證。系統不會出現在網際網路上，路由器也不用設定。

在這台機器與手機上安裝 Tailscale，用同一個帳號登入。
在這台機器上執行：
```
sudo tailscale serve --bg 8080
```
第一次執行時，如果 tailnet 還沒啟用這項功能，指令會印出 Serve is not enabled on your tailnet. 和一個連結。開啟連結照指示啟用（會一併開啟 HTTPS 憑證），再執行一次同一個指令。

完成後，tailscale serve status 會顯示這台機器的網址，例如 https://my-server.tail1234.ts.net。
照下方「調整 config.toml」把 public_url 設成這個網址，重新啟動系統。
手機開啟 Tailscale，再用瀏覽器開這個網址。

在 Linux 上，tailscale serve 需要 root 權限。不想每次都用 sudo 時，先執行一次 sudo tailscale set --operator=$USER。

--bg 設定的轉送會一直保留，重新開機後仍然有效。要停止時執行 sudo tailscale serve reset。

手機上的 Tailscale 沒有連線時，就連不到系統。

用 DDNS 與 Traefik

這個方式讓系統直接出現在網際網路上，任何地方都能用網域連線：

DDNS 讓一個網域永遠指向你家目前的對外 IP。家用網路的對外 IP 通常會變動，DDNS 服務會在變動時自動更新。下面的範例用免費的 DuckDNS。
Traefik 是反向代理：它向 Let's Encrypt 申請 HTTPS 憑證、自動續期，再把連線轉給系統。

開始前先確認

對外 IP 不是共用的。 在路由器的管理頁面找到 WAN IP，跟這台機器開 ifconfig.me 看到的 IP 比對。兩者不同，或 WAN IP 是 100.64. 到 100.127. 開頭時，代表網路業者讓多戶共用同一個對外 IP，外面連不進來，請改用 Tailscale。
路由器可以設定連接埠轉送。 要把 TCP 80 與 443 轉送到這台機器。80 埠是 Let's Encrypt 驗證網域用的，也負責把 http 轉到 https。
這台機器的區網 IP 固定。 在路由器替它保留一個 IP，否則連接埠轉送會在 IP 變動後失效。

申請 DuckDNS 網域

到 DuckDNS 登入，新增一個子網域，例如 my-budget，網域就是 my-budget.duckdns.org。
記下頁面上方的 token，下面的 compose 會用到。

docker-compose.yml

放在 Linux tarball 解壓縮出來的目錄，取代原本的 docker-compose.yml。把 my-budget.duckdns.org、your-duckdns-token、[email protected] 換成你自己的值。email 必須是真實的地址，Let's Encrypt 會拒絕 example.com 這類範例網域。

name: kakephooa

services:
  traefik:
    image: traefik:v3
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entrypoint.to=websecure
      - --entrypoints.web.http.redirections.entrypoint.scheme=https
      - --entrypoints.websecure.address=:443
      - [email protected]
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.httpchallenge.entrypoint=web
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt

  app:
    image: ghcr.io/single9/kakephooa:1.1.1
    restart: unless-stopped
    volumes:
      - ./config.toml:/app/config.toml:ro
      - data:/app/data
    labels:
      - traefik.enable=true
      - traefik.http.routers.kakephooa.rule=Host(`my-budget.duckdns.org`)
      - traefik.http.routers.kakephooa.entrypoints=websecure
      - traefik.http.routers.kakephooa.tls.certresolver=le
      - traefik.http.services.kakephooa.loadbalancer.server.port=8080

  ddns:
    image: lscr.io/linuxserver/duckdns:latest
    restart: unless-stopped
    environment:
      SUBDOMAINS: my-budget
      TOKEN: your-duckdns-token
      TZ: Asia/Taipei

volumes:
  data:
  letsencrypt:

app 沒有 ports：只有 Traefik 對外，系統只能經由 HTTPS 連到。
ddns 每 5 分鐘把目前的對外 IP 更新到 DuckDNS。
name: kakephooa 與 data volume 跟〈安裝〉章的範例相同，原本的資料會沿用。
Podman 沒有 /var/run/docker.sock，要先啟用 Podman 的 socket，並把這一行改成它的路徑。以非 root 使用者執行 Podman 時，預設不能使用 1024 以下的連接埠，80 與 443 需要另外設定。

啟動

照下方「調整 config.toml」修改設定，public_url 設成 https://my-budget.duckdns.org。
執行 docker compose up -d。
等一分鐘讓 Traefik 申請憑證，然後用手機的行動網路（不要連家裡的 Wi-Fi）開 https://my-budget.duckdns.org，確認從外面連得到。

憑證申請失敗時，用 docker compose logs traefik 查看原因，最常見的是 80 埠沒有轉送到這台機器。

系統出現在網際網路上之後

登入頁面任何人都開得到。請：

開啟兩步驟驗證（見〈帳號〉章）。
讓 signup_policy 維持 closed。
照〈安裝〉章的「升級」保持在最新版本。

調整 config.toml

不論用哪一種方式，都要把 [server] 改成手機實際連線的 HTTPS 網址，並開啟 secure_cookies：

[server]
public_url = "https://my-budget.duckdns.org"
secure_cookies = true

改完後重新啟動系統。之後一律用這個網址連線，包括在家裡的時候。用其他網址（例如 http://192.168.1.10:8080）開啟時，cookie 只在 HTTPS 下送出，會無法登入。

有設定 Google 登入時，Google Cloud Console 裡的授權重新導向 URI 也要改成新的網址加上 /auth/google/callback，例如 https://my-budget.duckdns.org/auth/google/callback。

加到主畫面

用 HTTPS 網址開啟系統之後：

iPhone（Safari）：按「分享」，選「加入主畫面」。
Android（Chrome）：按右上角的選單，選「加到主畫面」或「安裝應用程式」。

之後從主畫面的圖示開啟，就能離線記帳。