部署指南

本文檔介绍如何使用 Docker Compose 一鍵部署 OntiCards。

一、環境要求

項目	最低要求	推薦組態
CPU	2 核	4 核
記憶體	4 GB	8 GB
磁盘	20 GB	50 GB
Docker	20.10+	最新穩定版
Docker Compose	2.0+	最新穩定版

二、快速部署（3 步）

1
克隆項目倉庫

git clone https://github.com/stepll2026/OntiCards.git cd onticards

3
復製並填寫環境變數
4
```
cp .env.prod .env
```

# 数据库配置（系统自身数据库） DB_TYPE=mysql DB_HOST=localhost DB_PORT=3306 DB_NAME=onticards DB_USER=onticards DB_PASSWORD=your_password_here

6
LLM 配置（必填）

LLM_PROVIDER=openai # 或 qwen / moonshot 等 LLM_API_KEY=your_api_key_here LLM_BASE_URL= # 如需代理访问，填入代理地址
7
向量数据库（可选）

WEAVIATE_URL=http://localhost:8080
8
SSO 单点登录（可选，对接 JWT 模式 SSO 时配置，见用户手册第十五章）

SSO_SECRET_KEY=your_sso_shared_secret
9
ℹ️提示
详細的組態項說明請查看 .env.example 檔案中的註解。

一鍵啟動

docker-compose up -d

等待容器啟動完成後，訪問 http://localhost:3000

三、详細組態說明

3.1 LLM 組態

OntiCards 支持多種大語言模型提供商：

提供商	組態方式
OpenAI	`LLM_PROVIDER=openai` + `LLM_API_KEY`
阿裡通义千問	`LLM_PROVIDER=qwen` + `LLM_API_KEY`
月之暗面 Moonshot	`LLM_PROVIDER=moonshot` + `LLM_API_KEY`
本地模型	`LLM_PROVIDER=ollama` + `LLM_BASE_URL`

3.2 資料庫組態

系統預設使用 SQLite 作為本地資料庫（開箱即用，無需額外組態）。

如需使用 MySQL/PostgreSQL：

DB_TYPE=mysql
DB_HOST=your_mysql_host
DB_PORT=3306
DB_NAME=onticards
DB_USER=onticards
DB_PASSWORD=your_password

3.3 向量資料庫（可選）

向量資料庫用于存储數據卡片，支持以下選項：

選項	說明
內置 SQLite（預設）	無需額外組態，适合小規模使用
Weaviate	适合生產環境，支持分布式部署

組態 Weaviate：

WEAVIATE_URL=http://weaviate:8080
WEAVIATE_API_KEY=your_weaviate_key  # 如需认证

3.4 埠組態

預設埠映射：

服務	埠
前端	3000
後端 API	8000

如需修改，編輯 docker-compose.yml 中的埠映射。

四、常用運維命令

4.1 查看容器狀態

docker-compose ps

4.2 查看日誌

# 查看所有服务日志
docker-compose logs -f

# 查看后端日志
docker-compose logs -f backend

# 查看前端日志
docker-compose logs -f frontend

4.3 重啟服務

docker-compose restart

4.4 停止服務

docker-compose down

4.5 更新版本

git pull
docker-compose pull
docker-compose up -d

4.6 數據備份

# 备份数据库
docker-compose exec backend tar -czf /backup/db.tar.gz /app/data/

# 复制备份文件
docker-compose cp backend:/backup/db.tar.gz ./backup/

五、常见問題

5.1 啟動失败怎麼辦？

檢查 Docker 是否正常運行：

   docker --version
   docker-compose --version

查看日誌定位問題：

   docker-compose logs -f

確認埠未被占用：

   netstat -an | grep 3000  # Windows
   # 或
   lsof -i :3000           # Linux/Mac

5.2 LLM 調用失败？

確認 API Key 組態正確

檢查網絡是否能訪問 LLM 服務商

如需代理，確保 LLM_BASE_URL 組態了正確的代理地址

5.3 資料庫連接失败？

確認目標資料庫網絡可达

檢查防火墙設置

確認用戶名密碼正確

六、生產環境部署

6.1 HTTPS 組態

建議使用 Nginx 反向代理組態 HTTPS：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
    }

    location /api {
        proxy_pass http://localhost:8000;
    }
}

6.2 资源規劃

規模	日查詢量	推薦組態
小規模	< 1000	2 核 4G
中規模	1000-10000	4 核 8G
大規模	> 10000	8 核 16G + 集群

6.3 數據持久化

確保以下目錄或卷的數據被定期備份：

向量資料庫數據

組態檔案（.env）

七、卸載

# 停止并删除容器
docker-compose down

# 删除数据（谨慎操作，会丢失所有数据）
docker-compose down -v

# 删除项目文件
cd ..
rm -rf onticards

八、获取幫助

查看首次使用流程了解基本使用

查看問題排查指南解决常见問題

提交 Issue：https://github.com/stepll2026/OntiCards/issues