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

# 创建数据目录
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

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. 安装依赖

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

# 安装前端依赖
cd web
pnpm install

2. 启动服务

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

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

---

Docker 部署

1. 构建镜像

# 设置平台 (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. 部署到服务器

生产环境

# 创建数据目录
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

开发/测试环境

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

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

---

常用运维命令

# 查看容器日志
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权重计算

---

联系信息

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