HUAN 讙 · 開發者
開始開發
這一頁把 HUAN 從零跑起來，包含後台、Server、Worker 與一台模擬裝置。
需求
| 項目 | 版本 |
|---|---|
| Node.js | 24 LTS（見 .nvmrc） |
| pnpm | 12 |
| Docker | 用於 PostgreSQL 與 RustFS |
| FFmpeg | 只有在本機直接跑 Worker 時需要 |
npm install --global corepack@latest
corepack enable pnpm1. 安裝與設定
git clone https://github.com/linyao-tw/huan.git
cd huan
pnpm install
cp .env.example .env打開 .env，把 POSTGRES_PASSWORD 與 S3_SECRET_ACCESS_KEY 換成你自己的值，並確認 DATABASE_URL 裡的密碼一致。
2. 啟動 PostgreSQL 與 RustFS
pnpm docker:up這會啟動兩個容器並等到它們通過健康檢查。
3. 建立資料表
pnpm db:migrate4. 建立第一個管理員
HUAN 沒有公開註冊，也沒有預設密碼。第一個最高權限帳號由 CLI 建立：
pnpm --filter @huan/server admin:create指令會互動式地詢問 Email、帳號、顯示名稱與密碼。密碼至少 12 個字元。
在 Docker 環境或自動化流程裡可以改用非互動模式：
HUAN_ADMIN_PASSWORD='…' pnpm --filter @huan/server admin:create \
--email you@example.com --username admin --display-name 管理員5. 啟動開發環境
pnpm dev這會同時啟動：
| 服務 | 位址 |
|---|---|
| Admin | http://localhost:5173 |
| Server | http://localhost:4000 |
| Worker | 背景執行 |
用剛才建立的帳號登入 http://localhost:5173/login。
6.（選用）載入示範資料
想要一組可以直接點的內容：
pnpm db:seed種子資料包含幾台不同狀態的裝置、幾筆不同處理狀態的素材、一份 70/30 的已發布版面，以及早餐與午餐兩筆排程。
7. 啟動一台模擬裝置
不需要準備 Raspberry Pi 就能走完整條流程：
pnpm dev:device-sim終端機會顯示一組 XXXX-XXXX 配對碼。到後台的 /pair 輸入這組配對碼（或直接開啟終端機印出的網址），確認裝置資訊後綁定。
綁定後模擬裝置會：
- 連上 WebSocket
- 取得目標狀態
- 下載需要的素材並驗證 SHA-256
- 回報 ACK
- 開始送 heartbeat
終端機會即時顯示目前的版面修訂、目標與回報版本，以及素材同步進度。
8. 走一次完整流程
- 上傳影片：
/app/media→ 拖入一支 MP4。狀態會依序變成上傳中 → 處理中 → 就緒。 - 建立版面：
/app/layouts→ 新增 1920×1080 的版面。 - 切分畫面：在編輯器裡對根區塊做水平分割，把比例拖到 70/30。
- 放內容：把影片從左側素材面板拖進左邊的區塊，右邊的區塊放一段文字。
- 發布：按發布，建立第一個修訂。
- 指派：到
/app/devices/:id把這份版面設為裝置的預設版面。 - 觀察：模擬裝置會收到通知、下載影片、驗證雜湊、切換版面，後台的回報版本會跟上目標版本。
- 測試離線：
docker compose -f docker/compose.yaml stop，模擬裝置會繼續播放並持續重試連線。
啟動 Electron 播放器
pnpm dev:device開發模式下是視窗模式；正式打包後預設全螢幕 kiosk。