個人品牌網站與作品集系統,包含公開網站、後台管理桌面應用、以及背景排程服務。
┌─────────────────┐ ┌──────────────────┐
│ website/ │ │ admin-app/ │
│ Next.js 16 │◄────│ Electron + React │
│ 公開網站 + API │ │ 桌面後台管理 │
└────────┬────────┘ └──────────────────┘
│ │
│ ┌──────────────────┘
▼ ▼
┌──────────────────┐
│ PostgreSQL │
│ (Neon) │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ render-service/ │
│ 背景排程服務 │
│ 發佈文章 + 郵件通知│
└──────────────────┘
| 元件 | 技術 | 部署平台 |
|---|---|---|
| website/ | Next.js 16 + React 19 + Tailwind CSS 4 + Drizzle ORM | Vercel |
| admin-app/ | Electron + React 19 + Vite 6 | macOS DMG (electron-builder) |
| render-service/ | Express + node-cron + Nodemailer | Render.com Worker |
| 資料庫 | PostgreSQL (Neon Serverless) | Neon |
- Node.js ≥ 20
- pnpm ≥ 9(專案使用 pnpm workspace)
- PostgreSQL 資料庫(建議使用 Neon)
- Vercel 帳號(部署網站)
- Render.com 帳號(部署背景服務,可選)
- SMTP 服務(聯絡表單郵件通知,可選)
前往 Neon Console → Create Project → 選擇區域。
取得連線字串:
postgresql://<user>:<password>@<host>/<dbname>?sslmode=require
Schema 定義在 website/src/db/schema.ts,包含以下資料表:
- posts — 部落格文章(雙語、支援排程發佈)
- projects — 作品集
- services — 服務項目
- contacts — 聯絡表單留言
- api_keys — API 金鑰管理
- site_settings — 網站設定(key/value,JSONB)
使用 Drizzle Kit 推送 Schema:
cd website
pnpm install
pnpm db:setup # 執行 drizzle-kit push,建立所有資料表(含 site_settings)也可用
pnpm db:migrate走 migration 檔(website/drizzle/*.sql)。兩者皆會建立site_settings表;少了它,網站每個請求都會 500。
在 Vercel Project Settings → Environment Variables 中設定:
| 變數 | 說明 |
|---|---|
DATABASE_URL |
PostgreSQL 連線字串 |
NEXT_PUBLIC_SITE_URL |
網站公開網址 |
ADMIN_INIT_TOKEN |
初始化金鑰令牌(強烈建議,防止他人搶先初始化)。產生方式:node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"。首次產生管理金鑰後可移除。 |
ALLOWED_ORIGINS |
CORS 白名單(逗號分隔的 origin,如 https://admin.example.com)。未設則 fallback 為 *(僅建議本機開發)。Electron 桌面 admin app 不帶 Origin,不受此限。 |
# 安裝 Vercel CLI(選用)
pnpm add -g vercel
# 登入 Vercel
vercel login
# 一鍵部署
cd website
vercel --prod或直接連接 GitHub 倉儲 → Vercel Import → 設定 Framework 為 Next.js → 填入環境變數 → Deploy。
部署完成後,呼叫初始化 API 取得管理員 API Key。若設定了 ADMIN_INIT_TOKEN,請求必須帶上對應的 header(未帶會回 401,這是為了防止他人搶先初始化取得金鑰):
# 有設 ADMIN_INIT_TOKEN 時:
curl -X POST https://<your-domain>/api/admin/init \
-H "X-Admin-Init-Token: <你的令牌>"
# 本機開發未設令牌時可直接呼叫:
curl -X POST http://localhost:3000/api/admin/init回傳的 raw 即為管理員金鑰,請立即儲存(僅顯示一次)。取得金鑰後建議從 Vercel 環境變數移除 ADMIN_INIT_TOKEN,關閉初始化入口。
背景服務負責:
- 每分鐘:檢查並發佈排程文章
- 每 5 分鐘:寄送新聯絡表單的通知郵件
render-service/render.yaml 已預先配置。在 Render.com Dashboard:
- → Blueprint → 連結 GitHub 倉儲
- Render 會自動讀取
render.yaml - 填入以下 Secret Files:
| 變數 | 說明 |
|---|---|
DATABASE_URL |
同 Website 使用的 Neon 連線字串 |
SMTP_HOST |
SMTP 伺服器 |
SMTP_PORT |
SMTP 埠號(預設 587) |
SMTP_USER |
SMTP 帳號 |
SMTP_PASS |
SMTP 密碼 |
NOTIFY_EMAIL |
接收通知的 Email |
cd render-service
pnpm install
pnpm build
pnpm start或使用 Docker(自行撰寫 Dockerfile):
docker run -e DATABASE_URL=... -e SMTP_HOST=... ... node:20-alpine node dist/index.js桌面後台管理應用,連線到 Website 的 API 進行內容管理。
cd admin-app
pnpm install
pnpm build:mac產出檔案在 admin-app/release/Personal Web Admin-<version>.dmg。
cd admin-app
pnpm dev- 開啟 Admin App
- 輸入 Website 網址(如
https://your-domain.vercel.app) - 輸入從
/api/admin/init取得的管理員 API Key - 開始管理內容(文章、作品、服務、聯絡留言)
支援多組 Profile 切換(Multiple Server / API Key)。
# 使用 Docker 啟動 PostgreSQL
docker run -d --name personal-web-db \
-e POSTGRES_USER=dev \
-e POSTGRES_PASSWORD=dev \
-e POSTGRES_DB=personal_web_dev \
-p 5432:5432 postgres:16-alpinecp website/.env.example website/.env.local
# 編輯 .env.local 填入 DATABASE_URL(本地 PostgreSQL 連線字串)# 在根目錄安裝所有子專案
pnpm install
# 或分別安裝
cd website && pnpm install
cd admin-app && pnpm install
cd render-service && pnpm install# Terminal 1 — 網站
cd website
pnpm dev # http://localhost:3000
# Terminal 2 — 背景服務
cd render-service
pnpm dev # http://localhost:3001
# Terminal 3 — 後台管理(可選)
cd admin-app
pnpm devSchema 推送(建立所有資料表,包含 site_settings):
cd website
pnpm db:setup初始化管理員金鑰(網站需先 pnpm dev 啟動):
curl -X POST http://localhost:3000/api/admin/init| 變數 | 必要 | 說明 |
|---|---|---|
DATABASE_URL |
✅ | PostgreSQL 連線字串 |
NEXT_PUBLIC_SITE_URL |
網站公開網址 | |
ADMIN_INIT_TOKEN |
初始化金鑰令牌(強烈建議,首次部署後可移除) | |
ALLOWED_ORIGINS |
CORS 白名單(逗號分隔),未設則 fallback * |
註:早期版本文件曾列出
AUTH_SECRET(NextAuth.js 用),但本系統實際使用自訂 API Key 驗證(X-Api-Keyheader),不需要AUTH_SECRET。
| 變數 | 必要 | 說明 |
|---|---|---|
DATABASE_URL |
✅ | PostgreSQL 連線字串 |
SMTP_HOST |
SMTP 伺服器 | |
SMTP_PORT |
SMTP 埠號(預設 587) | |
SMTP_USER |
SMTP 帳號 | |
SMTP_PASS |
SMTP 密碼 | |
NOTIFY_EMAIL |
通知收件者 Email |
網址:https://<your-domain>.vercel.app
功能:
- 關於我 — 個人簡介與經歷
- 作品集 — 專案作品展示(由 Admin 後台管理)
- 部落格 — 雙語文章(支援排程發佈)
- 服務項目 — 收費服務介紹
- 聯絡表單 — 訪客留言(透過 Render Service 發送 Email 通知)
首次設定:
- 開啟 App → 輸入 Server URL(如
https://your-domain.vercel.app) - 取得 API Key:
curl -X POST https://your-domain.vercel.app/api/admin/init - 輸入 API Key → 登入成功
管理功能:
| 功能 | 說明 |
|---|---|
| Dashboard | 總覽統計(文章、作品、服務數量) |
| Posts | 文章列表 → 新增/編輯/刪除,支援草稿/排程發佈/雙語內容 |
| Projects | 作品管理 → 標題、描述、標籤、連結、圖片 |
| Services | 服務項目管理 → 價格、圖示、排序、上架/下架 |
| Contacts | 聯絡表單留言檢視 |
| Settings | 多 Profile 切換、API Key 管理 |
文章編輯器支援:
- Markdown 語法(react-markdown)
- 中英文雙語內容分開編輯
- 排程發佈(設定未來時間,由 Render Service 自動發佈)
- 草稿模式
部署 Render Service 後會自動執行:
- 每分鐘:掃描
draft=true且publishAt <= now的文章 → 自動設為已發佈 - 每 5 分鐘:掃描未通知的聯絡表單 → 透過 SMTP 發送 Email 通知
健康檢查:GET https://<render-service-url>/health
personal web/
├── index.html # 獨立手機版品牌頁面 (PWA style)
├── website/ # Next.js 16 公開網站 + API
│ └── src/
│ ├── app/ # App Router 頁面與 API Routes
│ ├── components/ # 共用元件
│ ├── db/ # Drizzle ORM Schema & 連線
│ └── lib/ # 工具函式
├── admin-app/ # Electron 桌面後台管理
│ ├── electron/ # Electron main/preload
│ └── src/ # React 前端
│ ├── pages/ # 管理頁面
│ ├── components/ # 共用元件
│ └── lib/ # API client, i18n, store
├── render-service/ # Express 背景排程服務
│ └── src/
│ ├── index.ts # Express 服務 + Cron jobs
│ ├── db.ts # 資料庫連線
│ └── schema.ts # 共用 Schema (posts, contacts)
└── open-design/ # 獨立開源專案 (非本系統)