@ -1,40 +1,29 @@
# 部署启动文档
AI 数据库自动部署系统 - 部署与启动指南
# AI 数据库自动部署系统 - Docker 部署完整指南
## 目录
- [环境要求 ](#环境要求 )
- [方式一： ](#方式一docker-compose-一键部署推荐 )
- [方式二：本地开发环境部署 ](#方式二本地开发环境部署 )
- [快速启动 ](#快速启动 )
- [服务架构 ](#服务架构 )
- [数据库初始化 ](#数据库初始化 )
- [服务访问 ](#服务访问 )
- [配置说明 ](#配置说明 )
- [数据管理 ](#数据管理 )
- [常用运维命令 ](#常用运维命令 )
- [常见问题 ](#常见问题 )
---
## 环境要求
### Docker 部署环境
| 软件 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Docker | 20.10+ | 24.x |
| Docker Compose | 2.0+ | 2.20+ |
### 本地开发环境
| 软件 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Miniconda/Anaconda | - | 最新版 |
| Python | 3.10+ | 3.10.x |
| Node.js | 20.x | 20.x LTS |
| PostgreSQL | 15+ | 15.x |
| Redis | 7+ | 7.x |
| MySQL | 8.0+ | 8.0.x |
---
## 方式一：
## 快速启动
### 1. 克隆项目
@ -46,257 +35,277 @@ cd <项目目录>
### 2. 启动所有服务
```bash
# 构建并启动所有服务
# 构建并启动（首次需要 --build）
docker-compose up -d --build
# 查看服务状态
docker-compose ps
# 查看日志
# 查看实时 日志
docker-compose logs -f
```
### 3. 服务组件说明
### 3. 访问应用
- 前端应用：
- 后端 API：
- API 文档：
---
## 服务架构
### 服务组件一览
| 服务名 | 容器名 | 端口映射 | 说明 |
|--------|--------|----------|------|
| postgres-meta | meta_postgres | 5432:5432 | 业务数据库 (PostgreSQL) |
| postgres-meta | meta_postgres | 5432:5432 | 业务元 数据库 (PostgreSQL) |
| mysql-user | user_mysql | 3306:3306 | 用户数据库资源池 (MySQL) |
| postgres-user | user_postgres | 2345:5432 | 用户数据库资源池 (PostgreSQL) |
| redis | redis | 6379:6379 | 缓存 & 消息队列 |
| chromadb | chromadb | 8100:8000 | 向量数据库 |
| backend | backend | 8000:8000 | 后端 API 服务 |
| celery_worker | celery | - | Celery 异步任务 |
| frontend | frontend | 3000:3000 | 前端服务 |
### 4. 初始化数据库
首次启动后，需要初始化数据库表结构：
```bash
# 进入后端容器
docker exec -it backend bash
# 执行数据库初始化（如有迁移脚本）
# python -m alembic upgrade head
```
| chromadb | chromadb | 8100:8000 | 向量数据库 (RAG 检索) |
| backend | backend | 8000:8000 | 后端 API 服务 (FastAPI) |
| celery_worker | celery | - | Celery 异步任务处理 |
| frontend | frontend | 3000:3000 | 前端服务 (React + Vite) |
或使用项目根目录的 SQL 文件：
### 网络架构
```bash
# 复制 SQL 到 PostgreSQL 容器并执行
docker cp postgresql.sql meta_postgres:/tmp/
docker exec -it meta_postgres psql -U admin -d auto_db_deployment -f /tmp/postgresql.sql
```
### 5. 停止服务
```bash
# 停止所有服务
docker-compose down
# 停止并删除数据卷（清除所有数据）
docker-compose down -v
┌─────────────────────────────────────────────────────────────────────┐
│ Docker Network (app-network) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ meta_postgres│ │ user_postgres│ │ user_mysql │ │
│ │ :5432 │ │ :5432 │ │ :3306 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └────────────┬────┴──────────────────┘ │
│ │ │
│ ┌───────────────────┴───────────────────┐ ┌─────────────┐ │
│ │ backend:8000 │───▶│ redis:6379 │ │
│ └───────────────────┬───────────────────┘ └─────────────┘ │
│ │ │
│ ┌───────────────────┴───────────────────┐ ┌─────────────┐ │
│ │ celery_worker │───▶│chromadb:8000│ │
│ └───────────────────────────────────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────┐ │
│ │ frontend:3000 │ │
│ └───────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
宿主机:5432 宿主机:2345 宿主机:3306
```
---
## 方式二：本地开发环境部署
### 1. 安装 Miniconda
## 服务访问
#### Windows
### 应用入口
1. 下载 [Miniconda Windows 安装包 ](https://docs.conda.io/en/latest/miniconda.html )
2. 运行安装程序，按提示完成安装
3. 打开 Anaconda Prompt 或 PowerShell
| 服务 | 地址 | 说明 |
|------|------|------|
| 前端应用 | http://localhost:3000 | 主应用入口 |
| 后端 API | http://127.0.0.1:8000 | API 服务 |
| Swagger UI | http://127.0.0.1:8000/docs | API 交互文档 |
| ReDoc | http://127.0.0.1:8000/redoc | API 参考文档 |
#### Linux / macOS
### 数据库连接信息
```bash
# 下载安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
#### 元数据库 (meta_postgres)
# 安装
bash Miniconda3-latest-Linux-x86_64.sh
| 项目 | 值 |
|------|-----|
| Host | localhost |
| Port | 5432 |
| Database | auto_db_deployment |
| Username | admin |
| Password | secure_2025 |
# 初始化 (重新打开终端或执行)
source ~/.bashrc
```bash
# 命令行连接
psql -h localhost -p 5432 -U admin -d auto_db_deployment
```
### 2. 创建 Python 环境
```bash
# 创建名为 backend 的 conda 环境
conda create -n backend python=3.10 -y
#### 用户 PostgreSQL (user_postgres)
# 激活环境
conda activate backend
| 项目 | 值 |
|------|-----|
| Host | localhost |
| Port | 2345 |
| Username | postgres |
| Password | root_secure_2025 |
# 验证 Python 版本
python --version
# 应输出: Python 3.10.x
```bash
# 命令行连接
psql -h localhost -p 2345 -U postgres
```
### 3. 安装后端依赖
#### 用户 MySQL (user_mysql)
| 项目 | 值 |
|------|-----|
| Host | localhost |
| Port | 3306 |
| Username | root |
| Password | root_secure_2025 |
```bash
# 进入后端目录
cd src/backend
# 命令行连接
mysql -h localhost -P 3306 -u root -p
```
# 配置国内 pip 镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com
---
# 安装依赖
pip install -r requirements.txt
```
## 配置说明
### 4. 启动基础设施服务
### Docker 内部 vs 宿主机连接
可以只用 Docker 启动数据库等基础服务 ：
Docker 容器内部使用服务名通信，宿主机使用映射端口 ：
```bash
# 仅启动数据库和缓存服务
docker-compose up -d postgres-meta mysql-user postgres-user redis chromadb
```
| 数据库 | Docker 内部地址 | 宿主机地址 |
|--------|-----------------|------------|
| meta_postgres | postgres-meta:5432 | localhost:5432 |
| user_postgres | postgres-user:5432 | localhost:2345 |
| user_mysql | mysql-user:3306 | localhost:3306 |
| redis | redis:6379 | localhost:6379 |
| chromadb | chromadb:8000 | localhost:8100 |
### 5. 配置后端
### 环境变量配置
编辑 `src/backend/config.yaml` ，确保数据库连接配置正确 ：
`docker-compose.yml` 中已配置所有必要环境变量，关键配置：
```yaml
env: dev
dev:
db:
host: localhost # 本地开发使用 localhost
port: 5432
database: auto_db_deployment
username: admin
password: secure_2025
redis:
host: localhost
port: 6379
chroma:
host: localhost
port: 8100
# 后端数据库连接
- DB__HOST=postgres-meta
- DB__PORT=5432
- DB__USERNAME=admin
- DB__PASSWORD=secure_2025
- DB__DATABASE=auto_db_deployment
# Redis
- REDIS__HOST=redis
- REDIS__PORT=6379
# ChromaDB
- CHROMA__HOST=chromadb
- CHROMA__PORT=8000
# 用户数据库资源池
- MYSQL__HOST=mysql-user
- MYSQL__PORT=3306
- POSTGRESQL__HOST=postgres-user
- POSTGRESQL__PORT=5432
```
### 6. 启动后端服务
---
```bash
# 确保在 backend conda 环境中
conda activate backend
## 数据管理
# 进入后端 app 目录
cd src/backend/app
### 数据卷
# 启动 FastAPI 服务
uvicorn server:my_app --host 0.0.0.0 --port 8000 --reload
```
| 数据卷名 | 说明 |
|----------|------|
| postgres_data | 元数据库数据 |
| postgres_user_data | 用户 PostgreSQL 数据 |
| mysql_data | 用户 MySQL 数据 |
| redis_data | Redis 持久化数据 |
| chroma_data | ChromaDB 向量数据 |
### 7. 启动 Celery Worker（ ）
### 备份与恢复
```bash
# 激活环境
conda activate backend
# 备份元数据库
docker exec meta_postgres pg_dump -U admin auto_db_deployment > backup_meta.sql
# 进入 app 目录
cd src/backend/app
# 恢复元数据库
docker exec -i meta_postgres psql -U admin auto_db_deployment < backup_meta.sql
# 启动 Celery Worker
celery -A celery_app worker --loglevel=info -Q celery,default,ai_tasks
# 备份用户 PostgreSQL
docker exec user_postgres pg_dump -U postgres < 数据库名> > backup_user.sql
```
### 8. 安装前端依赖
```bash
# 新开终端，进入前端目录
cd src/frontend
---
# 配置 npm 镜像源
npm config set registry https://registry.npmmirror.com/
## 常用运维命令
# 安装依赖
npm install
```
### 9. 启动前端服务
### 服务管理
```bash
# 开发模式启动
npm run dev
```
# 启动所有服务
docker-compose up -d
---
# 重新构建并启动
docker-compose up -d --build
## 服务访问
# 停止所有服务
docker-compose down
部署完成后，可通过以下地址访问各服务：
# 停止并删除数据卷（清除所有数据）
docker-compose down -v
| 服务 | 地址 | 说明 |
|------|------|------|
| 前端应用 | http://localhost:3000 | 主应用入口 |
| 后端 API | http://localhost:8000 | API 服务 |
| API 文档 | http://localhost:8000/docs | Swagger UI |
| ReDoc | http://localhost:8000/redoc | ReDoc 文档 |
# 重启单个服务
docker-compose restart backend
### 默认账户
# 查看服务状态
docker-compose ps
```
首次使用请参考项目初始化 SQL 或联系管理员获取默认账户信息。
### 日志查看
---
```bash
# 查看所有日志
docker-compose logs -f
## 环境变量配置
# 查看特定服务日志
docker-compose logs -f backend
docker-compose logs -f celery_worker
docker-compose logs -f frontend
```
### Docker 环境变量
### 进入容器调试
在 `docker-compose.yml` 中已配置好所有环境变量，无需额外设置。
```bash
# 进入后端容器
docker exec -it backend bash
### 本地开发环境变量
# 进入元数据库
docker exec -it meta_postgres psql -U admin -d auto_db_deployment
可创建 `.env` 文件或直接设置系统环境变量：
# 进入用户 PostgreSQL
docker exec -it user_postgres psql -U postgres
```bash
# 后端环境变量示例
export DB__HOST=localhost
export DB__PORT=5432
export DB__USERNAME=admin
export DB__PASSWORD=secure_2025
export DB__DATABASE=auto_db_deployment
export REDIS__HOST=localhost
export REDIS__PORT=6379
export CHROMA__HOST=localhost
export CHROMA__PORT=8100
# 进入用户 MySQL
docker exec -it user_mysql mysql -u root -p
```
---
### 常用 psql 命令
## 数据持久化
| 命令 | 说明 |
|------|------|
| `\l` | 列出所有数据库 |
| `\c <数据库名>` | 切换数据库 |
| `\dt` | 列出当前数据库的所有表 |
| `\d <表名>` | 查看表结构 |
| `\du` | 列出所有用户/角色 |
| `\q` | 退出 psql |
### Docker 数据卷
### 常用查询示例
| 数据卷名 | 说明 |
|----------|------|
| postgres_data | PostgreSQL 业务数据库数据 |
| postgres_user_data | PostgreSQL 用户数据库数据 |
| mysql_data | MySQL 用户数据库数据 |
| redis_data | Redis 持久化数据 |
| chroma_data | ChromaDB 向量数据 |
```sql
-- 查看所有数据库实例
SELECT instance_id, db_type, db_host, db_port, db_name, status
FROM database_instance;
### 备份数据
-- 查看所有项目
SELECT project_id, project_name, project_status, creation_stage
FROM project;
```bash
# 备份 PostgreSQL 数据
docker exec meta_postgres pg_dump -U admin auto_db_deployment > backup.sql
# 恢复数据
docker exec -i meta_postgres psql -U admin auto_db_deployment < backup.sql
-- 查看用户信息
SELECT user_id, username, email, status
FROM user_account;
```
---
@ -305,40 +314,22 @@ docker exec -i meta_postgres psql -U admin auto_db_deployment < backup.sql
### 1. Docker 构建慢
配置 Docker 镜像加速器：
配置 Docker 镜像加速器（ ） ：
```json
// Docker Desktop -> Settings -> Docker Engine
{
"registry-mirrors": [
"https://791bc246c9c148828358b6b170350f22.mirror.swr.myhuaweicloud.com",
"https://docker.mirrors.ustc.edu.cn",
"https://hub-mirror.c.163.com"
]
}
```
### 2. pip 安装依赖超时
确保已配置国内镜像源：
```bash
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
```
### 3. npm install 失败
确保已配置国内镜像源：
### 2. 端口被占用
```bash
npm config set registry https://registry.npmmirror.com/
```
### 4. 端口被占用
检查并释放占用的端口：
```bash
# Windows
# Windows - 查找占用端口的进程
netstat -ano | findstr :8000
taskkill /PID < PID > /F
@ -347,44 +338,40 @@ lsof -i :8000
kill -9 < PID >
```
### 5. 数据库连接失败
- 检查数据库服务是否启动
- 检查防火墙设置
- 确认连接配置（ ）
### 3. 数据库连接失败
### 6. Celery Worker 连接 Redis 失败
- 确认服务已启动：`docker-compose ps`
- 检查容器日志：`docker-compose logs postgres-meta`
- 确认端口映射正确
确保 Redis 服务已启动，且连接配置正确：
### 4. Celery Worker 连接 Redis 失败
```bash
# 测试 Redis 连接
redis-cli -h localhost -p 6379 ping
docker exec -it redis redis-cli ping
# 应返回: PONG
```
---
### 5. 前端无法连接后端
## 开发调试
检查 `src/frontend/vite.config.ts` 中的代理配置：
### 查看日志
- Windows/Mac Docker Desktop： `http://host.docker.internal:8000`
- Linux： `http://backend:8000`
```bash
# Docker 环境
docker-compose logs -f backend
docker-compose logs -f celery_worker
docker-compose logs -f frontend
# 本地环境
# 后端日志在 src/backend/logs/ 目录下
```
### 进入容器调试
---
## 停止与清理
```bash
# 进入后端容器
docker exec -it backend bash
# 停止服务（保留数据）
docker-compose down
# 进入数据库容器
docker exec -it meta_postgres psql -U admin -d auto_db_deployment
# 停止服务并删除所有数据
docker-compose down -v
# 清理未使用的镜像和容器
docker system prune -a
```
