guzhi/DEPLOYMENT.md

# 非遗资产估值系统 - 部署文档

## 项目概述

非遗资产估值系统是一个基于 Vue.js + FastAPI 的全栈应用，用于非物质文化遗产资产的价值评估。

- **前端**: Vue.js + Vite + pnpm
- **后端**: Python 3.11 + FastAPI + Tortoise ORM
- **数据库**: MySQL
- **容器化**: Docker

---

## 目录结构

```
youshu-guzhi/
├── app/                    # 后端 FastAPI 应用
│   ├── api/               # API 路由
│   ├── controllers/       # 业务控制器
│   ├── models/            # 数据库模型
│   ├── schemas/           # Pydantic 数据模型
│   ├── settings/          # 配置文件
│   └── utils/             # 工具函数和计算引擎
├── web/                    # 前端 Vue.js 应用
├── deploy/                 # 部署相关文件
│   ├── entrypoint.sh      # 容器启动脚本
│   └── web.conf           # Nginx 配置
├── Dockerfile             # Docker 构建文件
├── requirements.txt       # Python 依赖
└── run.py                 # 应用启动入口
```

---

## 环境配置

### 数据库配置

#### 使用 Docker 部署 MySQL

```bash
# 创建数据目录
mkdir -p ~/mysql-data

# 启动 MySQL 容器
docker run -d \
  --name mysql-valuation \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=your_password \
  -e MYSQL_DATABASE=valuation_service \
  -v ~/mysql-data:/var/lib/mysql \
  --restart=unless-stopped \
  mysql:8.0
```

#### 应用配置

配置文件位置: `app/settings/config.py`

```python
TORTOISE_ORM = {
    "connections": {
        "mysql": {
            "engine": "tortoise.backends.mysql",
            "credentials": {
                "host": "your_mysql_host",      # 数据库主机地址
                "port": 3306,                    # 数据库端口
                "user": "root",                  # 数据库用户名
                "password": "your_password",     # 数据库密码
                "database": "valuation_service", # 数据库名称
            },
        },
    },
    ...
}
```

### 第三方服务配置

| 服务 | 配置项 | 说明 |
|-----|-------|------|
| 阿里云短信 | `ALIBABA_CLOUD_ACCESS_KEY_ID/SECRET` | 短信验证码发送 |
| 阿里云邮件 | `SMTP_*` | 邮件发送 |

---

## 本地开发

### 1. 安装依赖

```bash
# 安装 Python 依赖
pip install -r requirements.txt

# 安装前端依赖
cd web
pnpm install
```

### 2. 启动服务

```bash
# 启动后端 (端口 9999)
python run.py

# 启动前端开发服务器 (另一个终端)
cd web
pnpm run dev
```

---

## Docker 部署

### 1. 构建镜像

```bash
# 设置平台 (M1/M2 Mac 需要)
export DOCKER_DEFAULT_PLATFORM=linux/amd64

# 构建镜像
docker build -t zfc931912343/guzhi-fastapi-admin:v3.9 .

# 推送到 Docker Hub
docker push zfc931912343/guzhi-fastapi-admin:v3.9
```

### 2. 部署到服务器

#### 生产环境

```bash
# 创建数据目录
mkdir -p ~/guzhi-data/static/images

# 拉取并运行
docker pull nbg2akd8w5diy8.xuanyuan.run/zfc931912343/guzhi-fastapi-admin:v3.9 \
  && docker rm -f guzhi_pro \
  && docker run -itd \
    --name=guzhi_pro \
    -p 8080:9999 \
    -v ~/guzhi-data/static/images:/opt/vue-fastapi-admin/app/static/images \
    --restart=unless-stopped \
    -e TZ=Asia/Shanghai \
    nbg2akd8w5diy8.xuanyuan.run/zfc931912343/guzhi-fastapi-admin:v3.9
```

#### 开发/测试环境

```bash
docker pull nbg2akd8w5diy8.xuanyuan.run/zfc931912343/guzhi-fastapi-admin:v3.9 \
  && docker rm -f guzhi_dev \
  && docker run -itd \
    --name=guzhi_dev \
    -p 9990:9999 \
    -v ~/guzhi-data/static:/opt/vue-fastapi-admin/app/static \
    --restart=unless-stopped \
    -e TZ=Asia/Shanghai \
    nbg2akd8w5diy8.xuanyuan.run/zfc931912343/guzhi-fastapi-admin:v3.9
```

---

## 端口说明

| 环境 | 容器名 | 主机端口 | 容器端口 |
|-----|-------|---------|---------|
| 生产 | guzhi_pro | 8080 | 9999 |
| 开发 | guzhi_dev | 9990 | 9999 |

---

## 数据持久化

容器挂载的数据目录:

```
~/guzhi-data/static/images  ->  /opt/vue-fastapi-admin/app/static/images
```

用于存储用户上传的图片文件（如非遗纹样图片、证书图片等）。

---

## 常用运维命令

```bash
# 查看容器日志
docker logs -f guzhi_pro

# 进入容器
docker exec -it guzhi_pro bash

# 重启容器
docker restart guzhi_pro

# 查看容器状态
docker ps | grep guzhi
```

---

## API 接口说明

| 模块 | 路径前缀 | 说明 |
|-----|---------|------|
| 用户端估值 | `/api/v1/app-valuations/` | 用户提交估值请求 |
| 管理端估值 | `/api/v1/valuations/` | 管理后台查看/审核 |
| 计算报告 | `/api/v1/valuations/{id}/report` | 获取计算过程报告 |

---

## 版本历史

| 版本 | 日期 | 说明 |
|-----|------|------|
| v3.9 | 2025-12-18 | 修复风险调整系数B3显示问题，添加计算过程详情 |
| v3.8 | 2025-12-18 | 修复历史传承度HI权重计算 |

---

## 联系信息

如有问题，请联系项目负责人。