部署指南

本文档介绍如何使用 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