HedgeDoc 筆記系統安裝教學（Ubuntu 24.04.3 + Docker）

自架屬於自己的 HackMD！由社長手把手實測、優化三天完成！

✨ 前言：從 HackMD 到 HedgeDoc 的開源回歸之路

HackMD 一直是許多工程師與筆記控的最愛，協作、Markdown、即時預覽，幾乎無可挑剔。
但隨著 HackMD 商業化步調加快、伺服器壅塞、外部連線不穩等問題逐漸浮現，開源社群便誕生了它的分支專案 —— HedgeDoc。

這款筆記軟體完整保留了 HackMD 的使用體驗與功能特性，同樣支援多人協作、Markdown 語法、高亮語法（code highlight）、甚至支援即時投影片模式。
最重要的是：完全開源、可自架、無需仰賴雲端伺服器。
換句話說，HedgeDoc 是「你在自己伺服器上重現 HackMD」的完美替代。

🧩 架設環境說明

本教學採用社長實測環境，經過 GPT、Trae、VS Code 等工具輔助優化三日，最終穩定運行。

項目	說明
作業系統	Ubuntu Server 24.04.3 LTS
部署方式	Docker + docker-compose
服務定位	局域網（LAN）內使用
使用者	單人 / 小型團隊筆記協作
測試平台	第十代 Intel 黑蘋果伺服器（Hackintosh）

雖然社長這台 10th Gen 黑蘋果原本是剪輯機，如今改成 AI 與開源實驗主機仍舊穩如老狗。硬體效能並非瓶頸，反倒讓這項開源計畫更具溫度與靈魂。

⚙️ 安裝步驟

1️⃣ 安裝 Docker 與 docker-compose

sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker

確認版本：

docker -v
docker-compose -v

2️⃣ 建立 HedgeDoc 專案目錄

mkdir ~/hedgedoc
cd ~/hedgedoc

3️⃣ 建立 `docker-compose.yml`

建立主設定檔：

version: "3.9"

services:
  postgres:
    image: postgres:16
    container_name: hedgedoc_postgres
    restart: always
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: strong_password
      POSTGRES_DB: hedgedoc
    volumes:
      - ./data/db:/var/lib/postgresql/data
    networks:
      - web

  app:
    image: quay.io/hedgedoc/hedgedoc:1.9.9
    container_name: hedgedoc_app
    restart: always
    environment:
      CMD_DB_URL: postgres://hedgedoc:strong_password@hedgedoc_postgres:5432/hedgedoc
      CMD_DOMAIN: 192.168.0.194
      CMD_PROTOCOL_USESSL: "false"
      CMD_PORT: 3000
      CMD_ALLOW_ORIGIN: "http://192.168.0.194"
      CMD_SESSION_SECRET: "changeme_secret"
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_ALLOW_EMAIL_REGISTER: "true"
      CMD_DEFAULT_PERMISSION: "limited"
      CMD_USE_BCRYPT: "true"
    depends_on:
      - postgres
    networks:
      - web

  caddy:
    image: caddy:2
    container_name: hedgedoc_caddy
    restart: always
    ports:
      - "80:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - web

networks:
  web:

4️⃣ 建立反向代理設定（Caddyfile）

:80 {
  encode gzip
  reverse_proxy http://hedgedoc_app:3000
  header {
    Access-Control-Allow-Origin  *
    Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
    Access-Control-Allow-Headers "Origin, Content-Type, Authorization"
  }
}

Caddy 的好處是配置簡潔、預設支援 HTTPS、自動憑證續期。如果你之後想公開部署，只要加上網域與憑證就能無痛升級。

5️⃣ 啟動服務

docker-compose up -d

檢查狀態：

docker ps

看到三個容器（hedgedoc_app、hedgedoc_postgres、hedgedoc_caddy）全部 Up，代表系統啟動成功。

6️⃣ 測試存取

開啟瀏覽器輸入：

http://192.168.0.194

若能看到 HedgeDoc 首頁畫面，恭喜你！自架版 HackMD 正式上線。
登入後即可建立新筆記，支援 Markdown、協作、匯出 HTML / PDF 等功能。

🛠️ 使用心得與優化方向

社長在三天測試過程中發現幾個重點：

記憶體占用輕盈：整套服務啟動僅需 300MB RAM 左右，非常適合小主機或家用伺服器。
局網穩定不掉線：斷線或重啟後筆記自動保存，不再擔心 HackMD 雲端服務掛點。
完全可控的資料安全性：資料存在自己硬碟中，不再依賴第三方雲端。
介面熟悉度高：幾乎 99% 與 HackMD 相同，使用者無需重新學習。
AI 工具整合性強：搭配 GPT、Trae、VS Code，可以實現「自動筆記生成」「Markdown 潤飾」等工作流。

💬 結語：開源精神的延續

HedgeDoc 讓筆記重新回到使用者手上。
它不是為了取代 HackMD，而是提醒我們：自由與可控性永遠是開發者最堅定的信仰。

這次的自架筆記伺服器不僅是技術實驗，更是一次「資料主權」的實踐。
在 AI 與雲端高速發展的年代，能擁有屬於自己的筆記空間，本身就是一種浪漫。

🚀 如果你也想嘗試自架 HedgeDoc，這份筆記就是最好的起點。