cbdb-online-main-server

中國歷代人物傳在線記录入系统原始碼。

授權 / License: CC BY-NC-SA 4.0 International (主要授權，詳見 LICENSE.md)

文件導覽（2026 更新）

開發指南

• AGENTS 指南 - AI 代理開發必讀
• 數據庫完整指南 - ⚠️ 必讀：環境、兼容性、Schema 管理
• Dev Container 使用說明 - VS Code / Codespaces 一鍵啟動開發環境
• CHANGELOG

開發手記

• 升級指南 - Laravel 框架升級記錄
• AdminLTE 在 CBDB Online 項目中的使用分析
• Proposal / Approval Flows
• 代碼表格前端實作比較
• 代碼表界面白名單維護
• 代碼表界面效能優化
• Posting/Office 流程備忘
• Resource TTS 注意事項
• 使用者權限說明
• 若需批次導入資料，請參考 BATCH_UPLOADERS
• CBDB 公共 API v1 說明
• 單向關係修復工具
• MERGE 工具說明
• 檢視表總覽
• Wiki 导入任务管理
• 姓名搜索索引管理
• SQLite 每週同步 - 自動匯出並同步到 HuggingFace

更多文檔

• AdminLTE 4 升級可行性
• AI 任官自動填充設計
• API 認證方案
• 稽核日誌提案
• 人物提案流程計畫
• BiogMain Repository 重構計畫
• 複合主鍵 URL 設計
• 資料庫 Schema（MySQL/SQLite）
• Laravel Query 審查
• MCP HTTP 介面提案
• MCP 使用指南
• 姓名搜尋效能改進
• Prometheus 指標說明
• Schema 文檔生成說明
• SQLite 數據發佈流程
• SQLite 遷移計畫

技術環境

生產環境

• PHP: 8.2+ (最低 8.2.0，建議 8.4)
• Laravel: 12.x (已從 11.x 升級，參見 UPGRADE.md)
• 數據庫: MariaDB 10.3.39 (Debian)
• Web Server: Caddy
• Node.js: 22.x（建議搭配 npm 10）

前端構建現況

• 全站已完成 AdminLTE 3 (Bootstrap 4) 升級，使用 Vite 構建系統。
• 主要入口：resources/js/app.js（UI 組件）、resources/js/datatables.js（DataTables）。
• resources/js/jquery-global.js 將 jQuery 暴露到全局；Bootstrap 4、AdminLTE 3、Select2 等在 app.js 中實現。
• 所有頁面均使用 @vite 載入前端資源，請勿引入外部 CDN 的 jQuery/Bootstrap，以免版本衝突。

⚠️ 重要：本專案現已升級到 Laravel 12.x 並要求 PHP 8.2+。建議使用 PHP 8.4 以獲得最佳性能和安全性。Laravel 12 已完全支持 PHP 8.4。

數據庫兼容性原則

⚠️ 重要：為保持未來遷移到其他數據庫實現的靈活性，請遵循以下原則：

• 避免使用特定數據庫專屬功能（如 MySQL 的 ngram parser、MariaDB 專屬插件）
• 優先使用標準 SQL 語法
• 如需使用數據庫特性，應在代碼中提供降級方案或文檔說明
• 索引策略應基於通用的 B-Tree 或其他跨數據庫支持的類型

帳號權限分離（重要）

基線 migration 會觸及完整 schema，為了降低事故風險，務必將一般應用連線與 migration 連線分離，避免日常帳號擁有過高權限。

配置原則：

• foo：一般應用使用者，僅需 CRUD 權限（不含 DROP/ALTER/CREATE）。
• foo_migrate：僅供 migration 使用的專用帳號，具備 schema 變更所需權限。

範例設定（.env）：

DB_USERNAME=foo
DB_PASSWORD=***

DB_MIGRATE_USERNAME=foo_migrate
DB_MIGRATE_PASSWORD=***

實際對應欄位請以 config/database.php 為準。

開發入口

常用命令

composer install
npm install
./vendor/bin/php-cs-fixer fix
./vendor/bin/phpunit
npm run build

前端

• React/Inertia 版 Query Playground 是現行主路徑：/app/query-playground
• 舊版 Blade Playground 僅保留相容性，不再新增功能
• 前端入口：
  • resources/js/app.js
  • resources/js/datatables.js
  • resources/js/inertia/**

後端

• 主要路由定義：routes/web.php
• Query Playground / Historical QA：
  • app/Http/Controllers/QueryPlaygroundController.php
  • app/Services/QueryPlaygroundService.php
  • app/Services/NaturalLanguageQueryService.php
• 複合主鍵定義：app/Support/CompositePrimaryKey.php

重要規則

• 複合主鍵表請使用 Query Builder，不要依賴 Eloquent 主鍵行為
• Migration 必須同時兼容 MariaDB/MySQL 與 SQLite
• 修改 resources/js/** 後，提交前請執行 npm run build
• commit message、介面文案與文檔使用繁體中文

更多說明

• 日常開發請先看 AGENTS.md
• 近期變更摘要請看 CHANGELOG.md
• 資料庫與 migration 規範請看 DATABASE.md

其他說明

• API 控制器位置：app/Http/Controllers/Api
• Windows 本地部署、TLS/SSL 與其他歷史維運說明，請優先查閱 docs/ 與相關 issue，不再在 README 展開維護。
• 若前端依賴異常，可依序嘗試：

rm -rf node_modules
npm cache clear --force
npm install
npm run build

• 建議使用 Node.js 22 與 npm 10；Ubuntu 可用 nvm 安裝。
• 若 storage/logs/laravel.log 無法寫入，請檢查 web server 使用者是否擁有該檔案權限。

SQLite 每週同步

本專案提供自動化腳本，將生產環境的數據庫匯出為 SQLite 格式，並同步到 HuggingFace 公開數據集 cbdb/cbdb-sqlite 供研究者下載使用。

最新下載入口：

• https://huggingface.co/datasets/cbdb/cbdb-sqlite/resolve/main/latest.zip
• https://input.cbdb.fas.harvard.edu/latest.zip

腳本位置

• 匯出腳本：scripts/export-daily-sqlite.sh - 將 MySQL/MariaDB 表格匯出為 SQLite
• 同步腳本：scripts/weekly-sqlite-sync.sh - 匯出、壓縮並上傳到 HuggingFace

前置安裝（Ubuntu）

# 安裝 zip 壓縮工具
sudo apt-get install zip

# 安裝 hf CLI
sudo apt-get install -y pipx
pipx install huggingface-hub
pipx ensurepath

HuggingFace 認證設定

腳本支持兩種認證方式（二擇一）：

# 方式一：hf auth login（推薦，token 安全存儲於 ~/.cache/huggingface/）
hf auth login

# 方式二：HF_TOKEN 環境變數
export HF_TOKEN=hf_你的token

# 驗證認證狀態
hf auth status

Access Token 設定：

1. 前往 https://huggingface.co/settings/tokens
2. Create new token → 選擇 Fine-grained
3. 勾選 Repositories → Write 權限
4. 複製 token 並在服務器上執行認證

Cron 定時任務

# 編輯 crontab
crontab -e

# 每週日凌晨 3 點執行（GMT+8）
0 3 * * 0 /path/to/cbdb-online-main-server/scripts/weekly-sqlite-sync.sh >> /var/log/cbdb-sqlite-sync.log 2>&1

手動執行

# 執行完整同步流程
bash scripts/weekly-sqlite-sync.sh

# 僅匯出 SQLite（不上傳）
bash scripts/export-daily-sqlite.sh

腳本流程說明

weekly-sqlite-sync.sh 執行以下步驟：

1. 前置檢查：確認 zip、hf 已安裝且 HuggingFace 認證有效
2. 匯出數據庫：呼叫 export-daily-sqlite.sh 產生 cbdb_YYYYMMDD.sqlite3 與 cbdb_YYYYMMDD.json
3. 壓縮檔案：產生 cbdb_YYYYMMDD.zip（zip 內使用平面檔名，不包含絕對路徑）
4. 上傳到 HuggingFace：將 history/cbdb_YYYYMM/cbdb_YYYYMMDD.zip、latest.zip、metadata/YYYY-MM/YYYY-MM-DD.json 及 latest.json（metadata 副本）以單一 commit 上傳至數據集倉庫
5. 清理：刪除所有臨時檔案（包括原始 SQLite 匯出檔與 metadata）