Bigcapital

Overview

Bigcapital 是一套開源會計與庫存管理系統，目標是為中小型企業提供一個可以自行託管（self-hosted）的財務管理平台。它涵蓋總帳、應收帳款、應付帳款、庫存管理、發票、報價單、財務報表等多項功能，並以 Web 介面操作，使用者只需透過瀏覽器即可使用。

Bigcapital 與 QuickBooks、Xero 等商業會計 SaaS 最大的分別，在於企業可以完全掌控自己的資料、擁有較高的靈活性，而且無需繳付月費。由於系統採用 Docker 容器化部署，因此可以安裝在各種 Linux 伺服器上。

在 Oracle Cloud Infrastructure（OCI）的 Always Free 方案中，Bigcapital 是其中一個常見的自架服務例子。OCI 提供永久免費的 ARM 架構 VM，配備一定比例的 CPU 與記憶體，足以運行 Bigcapital 所需的服務棧。對於開發者、小型會計師事務所以及初創公司來說，這是一個低成本建立私有會計系統的可行方案。

Architecture

Bigcapital 採用前後端分離的架構。前端是瀏覽器執行的單頁應用程式，後端則為 API 伺服器，並依賴以下基礎服務：

• MariaDB：主要資料庫，儲存公司帳目、客戶、供應商、庫存與交易紀錄。
• Redis：用作快取與佇列，提升 API 回應速度，並處理部分非同步工作。
• Gotenberg：容器化的 PDF 產生服務，負責將 HTML 轉換成 PDF，用於印發票、報價單及報表。
• API Server：執行業務邏輯，處理前端請求並與資料庫溝通。
• Web Client：由 Nginx 或 Caddy 伺服器提供的靜態網站資源。

以下是官方儲存庫中一個開發版 docker-compose.yml 的片段：

# WARNING!
# This is a development version of THE Bigcapital docker-compose.yml file.
# Avoid using this file in your production environment.
# We're exposing here sensitive ports and mounting code volumes for rapid development and debugging of the server stack.

version: '3.3'

services:
  mariadb:
    build:
      context: ./docker/mariadb
    environment:
      - MYSQL_DATABASE=${SYSTEM_DB_NAME}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
    volumes:
      - mysql:/var/lib/mysql
    expose:
      - '3306'
    ports:
      - '3306:3306'
    deploy:
      restart_policy:
        condition: unless-stopped

  redis:
    build:
      context: ./docker/redis
    expose:
      - '6379'
    ports:
      - '6379:6379'
    volumes:
      - redis:/data
    deploy:
      restart_policy:
        condition: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:7
    ports:
      - '9000:3000'

# Volumes
volumes:
  mysql:
    name: bigcapital_dev_mysql
    driver: local

  redis:
    name: bigcapital_dev_redis
    driver: local

要注意，這個檔案在註解中已經表明是「development version」，不應該直接用在生產環境。開發版為了方便偵錯，將 MariaDB、Redis 與 Gotenberg 的連接埠直接綁定到主機，這樣做會增加被攻擊的風險。正式部署時，應使用官方提供的 docker-compose.prod.yml，或者自行加上反向代理、TLS 終止和防火牆規則。

Deployment

在 Oracle Cloud 上部署 Bigcapital 的基本步驟如下：

1. 建立 VM 執行個體
   登入 OCI Console，建立一部 Ubuntu 22.04 或 24.04 的 VM。可以使用 Always Free 的 Ampere A1 ARM 型號，例如 4 OCPU、24GB RAM；如果只是測試，亦可以選擇較小配置。

2. 設定 VCN 安全規則
   於 Virtual Cloud Network（VCN）的 Security List 或 Network Security Group 中，只開放 SSH（22）、HTTP（80）與 HTTPS（443）。切勿將 3306、6379、9000 暴露至互聯網。

3. 安裝 Docker 與 Docker Compose
   在 VM 上執行官方安裝指令，並確認 docker compose 指令可以使用。

4. 取得 Bigcapital 原始碼
   使用 git clone 下載 Bigcapital 官方儲存庫，然後進入專案目錄。

5. 設定環境變數
   複製 .env.example 為 .env，並填入資料庫名稱、資料庫使用者、密碼、JWT 密鑰等設定。

6. 啟動服務
   如果只是開發測試，可以執行：

docker compose up --build

如果要用於正式環境，建議執行：

docker compose -f docker-compose.prod.yml up -d

1. 設定網域與 TLS
   在 Oracle Cloud DNS 中將域名指向 VM 的 Public IP，然後用 Nginx、Caddy 或 Let's Encrypt 取得 SSL 憑證。

2. 完成初始設定
   開啟瀏覽器，進入 Bigcapital Web 介面，建立管理員帳戶，然後開始設定公司會計資料。

Configuration

Bigcapital 的設定主要集中在 .env 檔案。常見的變數包括：

• SYSTEM_DB_NAME：MariaDB 的資料庫名稱。
• DB_USER 與 DB_PASSWORD：資料庫帳號及密碼。
• DB_ROOT_PASSWORD：MariaDB root 密碼。
• JWT_SECRET：API 簽發 JWT 用的秘密字串。
• MAIL_HOST、MAIL_PORT、MAIL_USER、MAIL_PASSWORD：SMTP 郵件設定，用於發送系統通知。

在 Oracle Cloud 環境中，需要特別注意以下安全設定：

• 使用 OCI 的 Network Security Group，限制 SSH 只允許來自自家 IP 的連線。
• 不要將 MariaDB 與 Redis 的連接埠綁定到 0.0.0.0。在生產環境，應讓資料庫只存在於 Docker 內部網絡。
• Gotenberg 服務本身沒有驗證機制，不應直接公開。API 伺服器應透過 Docker network 連接 gotenberg:3000。
• 定期更換 .env 中的密碼，並考慮使用 OCI Vault 管理敏感資料。

Operations

Bigcapital 的日常操作主要以 Docker Compose 指令為主。管理員需要熟悉以下指令：

• 查看所有服務狀態：

docker compose ps

• 查看 API 或資料庫日誌：

docker compose logs -f api
docker compose logs -f mariadb

• 重啟特定服務：

docker compose restart redis

• 備份資料庫：

docker compose exec mariadb mysqldump -u root -p bigcapital > backup.sql

• 升級 Bigcapital：

git pull
docker compose build
docker compose up -d

• 清理無用 Docker 資源：

docker system prune

由於 Oracle Cloud 免費方案的 boot volume 容量有限，日誌檔案與 Docker image 可能佔用大量磁碟空間。建議設定日誌輪替，並定期檢查磁碟使用率。若 API 回應緩慢，可以檢查 Redis 是否正常運作，以及 MariaDB 有沒有慢查詢。

FAQ

問：是否可以直接使用上面的開發版 docker-compose.yml 作生產環境？
答：不可以。開發版會暴露 3306、6379、9000 等敏感連接埠，而且沒有 TLS 終止與防火牆規則，只適合本機開發或偵錯。

問：Bigcapital 一定要部署在 Oracle Cloud 嗎？
答：不是。Bigcapital 可以部署在任何支援 Docker 的 VPS、雲端伺服器、NAS 或本地電腦。Oracle Cloud 只是一個常見的免費部署選項。

問：Gotenberg 的作用是什麼？
答：Gotenberg 是一個將 HTML 轉換成 PDF 的容器服務。Bigcapital 用它來產生發票、報價單、收據和財務報告。

問：Redis 是否必不可少？
答：是。Bigcapital 依賴 Redis 處理快取、佇列和暫時性資料，缺少 Redis 會導致系統無法正常運作。

問：如果不想自行維護，有沒有雲端版本？
答：官方有提供雲端 SaaS 服務，但本條目主要講解自架（self-hosted）方案。

Related Links

docker
litellm
oracle-cloud
MariaDB
redis
Gotenberg
QuickBooks
ERP

Source

Coverage auto (container scan)