Akaunting 3.1 — 自架複式記帳系統¶

Overview¶

Akaunting 是一套開源、網頁式會計系統，採用 PHP/Laravel 框架開發，支援複式記帳（Double-Entry Bookkeeping）。Akaunting 提供發票、付款、收款、客戶管理、供應商管理、銀行帳戶、損益表、資產負債表等功能，適合中小型機構使用。

本條目所描述的 Akaunting 3.1 實例，部署於 benhoweb.com 的 Oracle Cloud Infrastructure（OCI）Ampere A1（ARM64）運算實例上，屬於自架（Self-hosted）服務。部署方式以 Dockhand 作 Git-based stack 管理，所有敏感資料如資料庫密碼、管理員密碼等，不直接寫入 compose 檔案，而是經由 Dockhand 的環境變數與 secrets 注入。

目前服務公開網址為 https://akaunting.benhoweb.com。

Architecture¶

Akaunting 部署採用「單一 ARM64 主機 + 兩個 Docker 容器」的架構：

Akaunting 應用程式容器
使用 akaunting/akaunting:latest 映像，指定 platform: linux/arm64，以配合 Oracle Ampere A1 的 ARM64 架構。容器內執行 Akaunting 3.1（對應 Docker Hub 的 latest 版本標籤），並以 named volume akaunting-data 掛載 /var/www/html 保存程式檔案與上傳檔案。
MariaDB 資料庫容器
使用 mariadb:11.4 映像，同樣指定 platform: linux/arm64。此容器作為 Akaunting 的資料庫服務，容器名稱／服務名稱是 akaunting-db。Akaunting 透過 DB_HOST=akaunting-db 在 Docker network 內連接。

兩個容器都位於 Docker 自訂 bridge network cf_network 內。Akaunting 容器固定使用 IPv4 172.21.0.61；資料庫容器則一般配置為 172.21.0.62，避免重新建立容器時 IP 漂移。應用程式與資料庫之間透過 depends_on 與 healthcheck 控制啟動順序。

對外連線方面，Akaunting 容器不開放任何 host port。Cloudflare Tunnel 直接將 akaunting.benhoweb.com 的流量轉發至 172.21.0.61:80。因此主機層面沒有對外暴露的 HTTP 埠，符合「最少暴露面」的安全政策。

Deployment¶

部署工作由 Dockhand 負責。Dockhand 的 stack 定義存放在 Git repository 內，包含 docker-compose.yml、環境變數範本及 secrets 參照。當 Git repository 有新的 commit 或 tag，Dockhand 便會在主機上執行部署：

services:
  akaunting:
    image: akaunting/akaunting:latest
    platform: linux/arm64
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.61
    volumes:
      - akaunting-data:/var/www/html
    environment:
      AKAUNTING_SETUP: ${AKAUNTING_SETUP:-false}
      APP_URL: https://akaunting.benhoweb.com
      LOCALE: en-US
      DB_HOST: akaunting-db
      DB_PORT: "3306"
      DB_NAME: akaunting
      DB_USERNAME: akaunting
      DB_PASSWORD: ${AKAUNTING_DB_PASSWORD}
      DB_PREFIX: ${AKAUNTING_DB_PREFIX}
      COMPANY_NAME: ${AKAUNTING_COMPANY_NAME}
      COMPANY_EMAIL: ${AKAUNTING_COMPANY_EMAIL}
      ADMIN_EMAIL: ${AKAUNTING_ADMIN_EMAIL}
      ADMIN_PASSWORD: ${AKAUNTING_ADMIN_PASSWORD}
    depends_on:
      akaunting-db:
        condition: service_healthy

資料庫服務的 compose 定義大致如下：

  akaunting-db:
    image: mariadb:11.4
    platform: linux/arm64
    restart: unless-stopped
    networks:
      cf_network:
        ipv4_address: 172.21.0.62
    volumes:
      - akaunting-db-data:/var/lib/mysql
    environment:
      MARIADB_DATABASE: akaunting
      MARIADB_USER: akaunting
      MARIADB_PASSWORD: ${AKAUNTING_DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${AKAUNTING_DB_ROOT_PASSWORD}
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

第一次部署時，可將 AKAUNTING_SETUP 設為 true，或者直接提供 COMPANY_NAME、ADMIN_EMAIL、ADMIN_PASSWORD 等環境變數，讓 Akaunting 在容器啟動時自動初始化。Dockhand 的 secrets 功能會確保密碼不會寫入 Git 或 compose 檔案。

Configuration¶

Akaunting 的設定主要由容器環境變數控制。以下是常用的變數：

AKAUNTING_SETUP：控制是否執行網頁安裝程式。預設為 false，首次部署時通常設為 true。
APP_URL：應用程式公開網址，必須為 https://akaunting.benhoweb.com。
LOCALE：介面語系，目前使用 en-US。
DB_HOST：資料庫服務名稱，即 akaunting-db。
DB_PORT：MariaDB 連接埠，固定為 3306。
DB_NAME：資料庫名稱，為 akaunting。
DB_USERNAME：資料庫使用者，為 akaunting。
DB_PASSWORD：由 Dockhand environment 注入，不會以明文儲存於 Git。
DB_PREFIX：資料表字首，可由 Dockhand secret 指定，避免共用資料庫時衝突。
COMPANY_NAME、COMPANY_EMAIL：Akaunting 初始化時的機構資料。
ADMIN_EMAIL、ADMIN_PASSWORD：系統管理員帳號密碼，經 Dockhand secrets 注入。

MariaDB 方面，MARIADB_DATABASE、MARIADB_USER 與 Akaunting 的 DB_NAME、DB_USERNAME 必須一致；MARIADB_ROOT_PASSWORD 只應存放在 Dockhand secret，不應進入 public repository。

Operations¶

日常操作均建議透過 Dockhand 或 docker compose 指令完成。

更新 Akaunting：更新 Dockhand repository 中 akaunting/akaunting:latest 對應的版本，然後執行 Dockhand deploy。即時操作時，可使用 docker compose pull akaunting 與 docker compose up -d akaunting。
查看日誌：docker compose logs -f akaunting 可追蹤 PHP 錯誤、HTTP 請求及資料庫連線紀錄。
備份：需要備份兩部分。第一部分是 Akaunting 的 named volume akaunting-data；第二部分是 MariaDB 資料庫。可使用 docker compose exec akaunting-db mariadb-dump -u akaunting -p"$AKAUNTING_DB_PASSWORD" akaunting > akaunting-db.sql 匯出 SQL。
還原：先恢復 akaunting-data volume，再將 SQL dump 匯入 MariaDB。操作前應停用 Cloudflare Tunnel 或暫時停止 Akaunting 容器，避免資料不一致。
健康檢查：可使用 docker compose ps 查看兩個容器是否有 Up (healthy) 狀態；亦可直接瀏覽 https://akaunting.benhoweb.com 確認登入頁面正常。

FAQ¶

Q：Akaunting 3.1 是指那個版本？
A：本條目對應 Docker Hub 的 akaunting/akaunting:latest 映像。截至本網站建立紀錄，該映像的穩定版本線為 Akaunting 3.1，故此命名。

Q：為何 Akaunting 不直接對外開 port？
A：按照 benhoweb.com 的安全政策，所有容器不直接暴露 host port。Cloudflare Tunnel 是唯一的入口，只將網域流量轉發到內部容器 IP 172.21.0.61:80。

Q：如果我的服務跑在 Oracle Ampere A1，會比 x86 主機有問題嗎？
A：不會。Akaunting 與 MariaDB 都有提供 ARM64 映像。compose 內明確加入 platform: linux/arm64，確保 Docker 不會誤用其他架構的映像。

Q：Dockhand 如何處理密碼？
A：Dockhand 支援 secrets management。部署時，Dockhand 會把 ${AKAUNTING_DB_PASSWORD}、${AKAUNTING_ADMIN_PASSWORD} 等變數從安全環境中讀取，再注入容器環境。這些秘密不會寫入 Git。

Q：需要定期備份嗎？
A：需要。至少每日備份 MariaDB 的 SQL dump，以及定期備份 akaunting-data volume。若 Akaunting 安裝套件或上傳附件有變更，更要保留 volume 備份。

Source¶

Coverage auto (container scan)