open333CRM
全通路客戶關係管理系統，整合 LINE、Facebook Messenger、WebChat 多渠道客服，提供智能自動化、數據分析、行銷活動與粉絲互動功能。
核心功能
- 多渠道整合 — LINE OA、Facebook Messenger、Instagram (DM/Threads)、WebChat 統一收件箱
- 智能自動化 — 規則引擎（12 種動作類型）、LLM 情緒分析/分類/智能回覆、知識庫
- 數據分析 — 即時儀表板、績效追蹤、趨勢圖表、CSV 匯出
- 行銷系統 — 客群分眾、活動管理、廣播排程、模板變數替換、LINE Flex 素材匯入與編輯
- 案件管理 — Ticket 生命週期、SLA 監控、CSAT 調查
- 下游 Webhook — CRM 接收的 Webhook 可即時轉發至自訂第三方系統
- 短連結 — URL 縮短、QR Code、點擊追蹤、GA4/Meta Pixel 追蹤注入
- 權限管理 — 多租戶架構、ADMIN / SUPERVISOR / AGENT 三級 RBAC
技術架構
| 層級 | 技術 |
|---|
| 前端 | Next.js 15 + React 19 + Tailwind CSS + shadcn/ui |
| 後端 | Fastify 5 + TypeScript (ESM) |
| 資料庫 | PostgreSQL 16 + Prisma 6 |
| 快取 / 佇列 | Redis + BullMQ |
| 即時通訊 | Socket.IO (on Fastify) |
| AI | Gemini；Embedding 只支援 Ollama，見 AUDIT LLM-04 |
| 儲存 | MinIO (S3 相容) |
| 建構 | pnpm workspaces + Turborepo |
| 容器 | Docker Compose |
上傳檔案內容偵測
API 會在檔案進入 storage 或文件 parser 前，以檔案 bytes 驗證內容類型。系統在 Docker image 內固定包含 Magika model/config，API 啟動時 preload；執行期間只讀本地模型，不從 GitHub 或其他外部 URL 下載。偵測能力預設開啟：
UPLOAD_CONTENT_DETECTION_ENABLED=true
此功能可在偵測器故障時暫時關閉作為緊急回退：
UPLOAD_CONTENT_DETECTION_ENABLED=false
關閉後 API 會在啟動 log 發出 warning，且上傳只代表通過既有路由/MIME 流程，不代表檔案已完成內容驗證。修復問題後請改回 true 並重啟 API。內容類型偵測不是病毒掃描器；若需要 malware protection，必須另接隔離式 scanner。
Magika assets 使用固定的 standard_v3_3 model/config，checksum 記錄在 apps/api/assets/magika/standard_v3_3/SHA256SUMS。大型檔案的 presigned upload 必須先 PUT 到 quarantine key，再呼叫 authenticated POST /api/v1/files/complete-upload 完成偵測與 promote；未完成的 object 不可直接供業務流程使用。
專案結構
apps/
api/ # Fastify 後端 (port 3001)
web/ # Next.js 前端 (port 3000)
workers/ # BullMQ 消費者（獨立程序）
cli/ # oclif CLI (npm: open333)
widget/ # 嵌入式 WebChat widget
packages/
database/ # Prisma schema、migrations、seed
shared/ # 共用型別與工具
core/ # 共用工具函式
types/ # TypeScript 型別定義
ui/ # React UI 元件 (shadcn/ui)
automation/ # 自動化引擎 (json-rules-engine)
brain/ # AI/LLM 輔助程式，目前沒有 app 匯入
channel-plugins/ # LINE、Facebook、WebChat 插件
kb-ingest/ # 知識庫擷取管線
CLI 工具 (open333)
安裝：npm install -g @open333crm/cli 或專案內 pnpm --filter @open333crm/cli dev -- <command>
open333 login --host https://api.example.com --email [email protected] --profile prod
open333 status --json
open333 stats --from 2026-07-01 --to 2026-07-08 --json
open333 apis --json
完整 CLI 文件與擴充指南：docs/cli/SKILL.md
LLM / CLI 連線
讓 LLM（Claude、ChatGPT 等）或 open333 CLI 直接操作本系統。
產生 Token
- 登入後台 → 設定 → CLI 連線
- 點「產生 Token」，填名稱（例：
Claude Code）、選過期時間
- 複製完整 token（只會顯示一次）
給 LLM 使用
將 token 貼給 LLM，並附上以下資訊：
API Base URL: https://uat.open333crm.create360.ai
Bearer Token: <token>
在 Headers 中加上：
Authorization: Bearer <token>
或參考 Skill 文件：https://uat.open333crm.create360.ai/skill.md
給 CLI 使用
open333 login --host https://uat.open333crm.create360.ai
# 貼上 token
open333 status --json
open333 stats --from 2026-07-01 --json
open333 apis --json
管理 Token
- 在 設定 → CLI 連線 列出所有 token，可查看最後使用時間
- 不需要的 token 可直接撤銷，使用該 token 的 LLM/CLI 會立即失效
瀏覽器 WebMCP
登入後的 dashboard 支援 WebMCP。當瀏覽器提供 document.modelContext 時，CRM 會向瀏覽器代理註冊唯讀工具；不支援 WebMCP 的瀏覽器不會影響原有功能。
WebMCP 工具會使用目前登入頁面的 access JWT 呼叫既有 API，JWT 不會列為工具參數，也不會回傳給模型。後端仍會執行 JWT 驗證、tenant isolation 與 RBAC。
目前提供：
crm_search_contacts — 搜尋聯絡人crm_list_cases — 篩選案件與 SLA 狀態crm_get_case — 查詢單一案件crm_get_contact — 查詢單一聯絡人crm_get_analytics_overview — 查詢分析總覽（依既有角色權限）crm_get_current_agent — 查詢目前登入客服
本機驗收：
- 使用 Chrome 開啟
chrome://flags/#enable-webmcp-testing，啟用 WebMCP testing 後重新啟動瀏覽器。
- 登入 CRM dashboard。
- 使用 Chrome Model Context Tool Inspector 查看並呼叫工具。
WebMCP 仍是實驗性 Web API，詳細 API 請參考 Chrome WebMCP 文件。遠端 LLM / CLI 整合仍使用上方的 /mcp 與 CLI token 流程。
Passkey / WebAuthn 登入
Passkey 提供 Agent 使用 Touch ID、Face ID、Windows Hello、裝置 PIN 或安全金鑰登入。密碼登入仍保留作為復原方式。
啟用設定
API 使用專案根目錄的 .env。正式環境必須使用 HTTPS，且 WEBAUTHN_RP_ID 不可包含 protocol、port 或 path：
WEBAUTHN_RP_ID=crm.example.com
WEBAUTHN_RP_NAME=open333CRM
WEBAUTHN_ORIGIN=https://crm.example.com
WEBAUTHN_CHALLENGE_TTL_SECONDS=120
本機測試可使用：
WEBAUTHN_RP_ID=localhost
WEBAUTHN_RP_NAME=open333CRM
WEBAUTHN_ORIGIN=http://localhost:3000
Redis 需支援 GETDEL；專案 Docker Compose 使用 Redis 7。
綁定與管理位置
登入後台後，進入：
設定 → Passkey 登入 → 綁定 Passkey
Agent 可在此綁定多個裝置；綁定前會輸入裝置名稱（例如 MacBook Touch ID 或 iPhone），清單會顯示名稱、裝置類型與備份狀態，也可重新命名或撤銷既有 Passkey。登入頁的「使用 Passkey 登入」會使用已綁定的 credential；Passkey 流程要求 User Verification，並使用獨立的 rate limit 與一次性 challenge 防護。
Passkey API
所有端點都在 /api/v1/auth 底下：
| 方法 | 端點 | 用途 |
|---|
POST | /passkeys/register/options | 已登入 Agent 取得註冊選項 |
POST | /passkeys/register/verify | 驗證並儲存 Passkey public key |
POST | /passkeys/authentication/options | 取得登入 challenge |
POST | /passkeys/authentication/verify | 驗證 Passkey 並核發現有 JWT Session |
GET | /passkeys | 列出目前 Agent 的 Passkey |
PATCH | /passkeys/:id | 重新命名 Passkey |
DELETE | /passkeys/:id | 撤銷 Passkey（soft revoke） |
快速開始
前置需求
- Docker & Docker Compose（推薦路徑唯一需求）
- 或本機安裝 Node.js 26（與 Docker image 相同）、pnpm 9（透過 corepack 管理）。根目錄
package.json 的 engines 也接受 24.22.1 以上
啟動（推薦：全容器化開發環境，支援 hot reload）
git clone [email protected]:CreateIntelligens/open333crm.git
cd open333crm
cp .env.api.example .env.api
cp .env.web.example .env.web
cp .env.workers.example .env.workers
# 第一次啟動：build image、安裝依賴、跑 migration/seed（需要幾分鐘）
docker compose -f docker-compose.dev.yml up --build
# 之後日常啟動
docker compose -f docker-compose.dev.yml up
- Web：
http://localhost:3000 API：http://localhost:3001
- 整個 repo 掛載為 bind mount。你修改
apps/* 或 packages/* 下的任何檔案，容器會立即套用變更：apps/api、apps/workers 用 tsx watch 自動重啟，apps/web 用 Next.js Fast Refresh 熱更新，packages/* 用 tsc --watch 重新編譯。詳細機制請見 docker-compose.dev.yml 內的註解
- Postgres 對外 5433、Redis 對外 6380、MinIO 對外 9000（console 為 9001）
另一種方式：本機直接跑 app（Docker 只跑基礎設施）
pnpm install
docker compose up -d postgres redis minio
cp apps/api/.env.example .env # 根目錄，API 讀這個
cp .env.web.example apps/web/.env.local
# 把 apps/web/.env.local 內的 NEXT_PUBLIC_API_URL 改成 http://localhost:3001/api
pnpm db:generate
pnpm --filter @open333crm/database exec prisma migrate deploy
pnpm db:seed
pnpm dev # 同時啟動 API + Web
pnpm --filter @open333crm/api dev # 僅 API
pnpm --filter @open333crm/web dev # 僅 Web
API 從專案根目錄的 .env 讀取，不是 apps/api/.env。
登入
資料庫 seed 完成後，你可以用預設帳號登入。密碼請查看 packages/database/prisma/seed-data/demo-accounts.ts。
這些帳號只在本機開發建立。NODE_ENV=production 時 seed 不建它們，除非設定 SEED_DEMO_ACCOUNTS=true。帳號已經存在時，seed 不會覆寫它的密碼與啟用狀態。
常用指令
pnpm db:generate # 重新生成 Prisma Client
pnpm db:migrate -- --name <name> # 建立新 migration
pnpm build # 全部 build
pnpm lint # 全部 lint
Docker 環境
docker compose ps # 查看狀態
docker compose logs -f api # 看 API log
docker compose restart api # 重啟 API
docker compose down # 停止
docker compose down -v # 停止並刪除 volumes（危險）
macOS：export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"
API
Base URL: http://localhost:3001/api/v1，JWT Bearer Token 認證。
主要端點：
| 模組 | 端點 |
|---|
| 認證 | POST /auth/login、GET /auth/me |
| 對話 | GET /conversations、POST /conversations/:id/messages |
| 案件 | GET /cases、POST /cases |
| 聯絡人 | GET /contacts、POST /contacts |
| 自動化 | GET /automation/rules、POST /automation/rules |
| 分析 | GET /analytics/overview、POST /analytics/export |
| 行銷 | GET /marketing/campaigns、POST /marketing/broadcasts |
| 短連結 | GET /shortlinks、POST /shortlinks |
| 追蹤設定 | GET /settings/tracking、PUT /settings/tracking |
| 渠道管理 | GET /channels、POST /channels、PUT /channels/:id |
| Webhook | GET /webhooks、POST /webhooks、DELETE /webhooks/:id |
完整 API 文件：docs/api-endpoints.md（109+ 端點）
WebSocket 事件
連線 ws://localhost:3001，需 JWT token。
socket.on("message:new", (data) => {}); // 新訊息
socket.on("conversation:updated", (data) => {}); // 對話更新
socket.on("case:updated", (data) => {}); // 案件更新
socket.on("notification", (data) => {}); // 通知
部署
本地開發
docker compose up -d
# http://localhost（Caddy 反向代理 port 80）
線上部署
cp .env.prod.example .env.prod # 填入 DOMAIN、CERTBOT_EMAIL
docker compose -f docker-compose.prod.yml up -d
SSL 由 certbot 自動續約，無需手動操作。
環境變數檔案
| 檔案 | 用途 |
|---|
.env.api | API（DB、Redis、JWT 等，docker-compose*.yml 讀這個） |
.env.workers | Workers |
.env.web | Web 前端（docker-compose*.yml 讀這個） |
.env.prod | 線上部署（DOMAIN、CERTBOT_EMAIL） |
.env（根目錄，選用） | 只有本機直接執行 pnpm --filter @open333crm/api dev（不透過 Docker）時才需要。API 會從專案根目錄讀取這個檔案 |
生產環境必須修改
故障排除
| 問題 | 解決 |
|---|
| PostgreSQL 連線失敗 | Docker port 是 5433（非 5432），確認 DATABASE_URL |
| Redis 連線失敗 | Docker port 是 6380（非 6379），確認 REDIS_URL |
| Docker 指令找不到 | macOS: export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH" |
| Prisma Client 找不到 | pnpm db:generate |
| LINE/FB Webhook 收不到 | 確認使用公開 URL + 正確 webhook 格式 |
貢獻
- Fork →
git checkout -b feat/xxx → git commit -m 'feat: xxx' → PR
- Commit 遵循 Conventional Commits
授權
GNU General Public License v3.0
Built with ❤️ by CreateIntelligens Team
