Skip to content

README.md

Latest commit

 

History

History
185 lines (137 loc) · 5.99 KB

README.md

File metadata and controls

185 lines (137 loc) · 5.99 KB

FastapiAdmin 部署说明

与仓库根文档的关系：项目总览、快速开始、演示账号等请以 根目录 README.md 为准；本文档侧重 Docker 部署的详细操作。

项目结构

docker/
├── backend/                # 后端服务配置
│   └── Dockerfile          # 后端 Dockerfile（多阶段构建）
├── nginx/                  # Nginx 配置
│   ├── nginx.conf          # Nginx 配置文件
│   ├── ssl/                # SSL 证书目录（需自行放置证书文件）
│   │   └── .gitkeep        # 保留目录结构
│   ├── web/                # 前端静态文件（放置 dist/ 后部署）
│   │   └── .gitkeep
│   ├── app/                # 移动端 H5 静态文件（放置 dist/ 后部署，按需启用）
│   │   └── .gitkeep
│   └── docs/               # 文档网站静态文件（放置 dist/ 后部署，按需启用）
│       └── .gitkeep
├── mysql/                  # MySQL 持久化目录
│   └── .gitkeep            # 容器运行后自动产生数据文件
├── redis/                  # Redis 持久化目录
│   └── .gitkeep            # 容器运行后自动产生数据文件
├── docker-compose.yaml     # Docker Compose 编排文件
├── .env                    # 环境变量配置文件（.gitignore 已排除）
├── .env.example            # 环境变量示例文件
├── env.sh                  # 环境变量加载脚本
└── README.md               # 本文档

.gitkeep 仅用于保留空目录结构，不包含任何实际内容。

部署准备

系统依赖

  • Docker (>= 20.10)
  • Docker Compose (v2，Docker 内置的 docker compose 命令)

环境配置

  1. 配置环境变量

    cp .env.example .env
chmod 600 .env  # 限制权限，防止其他用户读取密码

    主要配置项：

    变量 说明
    MYSQL_ROOT_PASSWORD MySQL 根密码
    MYSQL_DATABASE 数据库名
    MYSQL_USER 数据库用户
    MYSQL_PASSWORD 数据库密码
    REDIS_PASSWORD Redis 密码
    BACKEND_PORT 后端服务端口
    HTTP_PORT HTTP 端口
    HTTPS_PORT HTTPS 端口

  2. SSL 证书配置（可选，但生产环境必须）

    将 SSL 证书文件放在 nginx/ssl/ 目录下：

    # 自签名证书（测试用）：
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout docker/nginx/ssl/server.key \
  -out docker/nginx/ssl/server.pem \
  -subj "/CN=service.fastapiadmin.com"

# 生产环境请使用正规 CA 签发的证书

部署方式

方式一：使用部署脚本（推荐）

在项目根目录执行：

./deploy.sh

脚本会自动执行：检查依赖 → 创建目录 → 停止旧容器 → 更新代码 → 构建镜像 → 启动容器 → 验证部署 → 清理旧资源。

命令选项

命令 说明
./deploy.sh 完整部署流程
./deploy.sh start 启动所有容器
./deploy.sh stop 停止所有容器
./deploy.sh restart 重启所有容器
./deploy.sh logs 查看所有容器日志
./deploy.sh verify 验证部署状态
./deploy.sh clean 清理旧镜像
./deploy.sh --build-frontend 完整部署并构建前端
./deploy.sh --skip-frontend 完整部署并跳过前端构建（默认）

方式二：手动操作

cd docker

# 启动所有服务
docker compose --env-file .env up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f [service_name]

# 停止服务
docker compose down

# 仅重建某个服务
docker compose up -d --no-deps --build [service_name]

容器资源限制

服务 CPU 限制 内存限制 内存预留
MySQL 无限制 1 GB 256 MB
Redis 无限制 512 MB 128 MB
Backend 1 核 1 GB 256 MB
Nginx 0.5 核 256 MB 64 MB

如需调整，修改 docker-compose.yaml 中对应服务的 deploy.resources 字段。

访问信息

部署完成后，可以通过以下地址访问：

服务 地址
前端 https://域名(或 ip)/web
API 文档 https://域名(或 ip)/api/v1/docs
登录信息 账号 admin，密码 123456

注意: docs 和 app 目录默认不参与部署，如需启用请取消 docker-compose.yaml 中相关配置注释。

日志管理

# 查看所有容器日志
./deploy.sh logs

# 查看实时日志
cd docker
docker compose logs -f [服务名]

# 服务名：backend, nginx, mysql, redis

各容器的日志会被 Docker 自动轮转，限制为每个容器最多保留 3 个日志文件，每个最大 10MB。可在 docker-compose.yaml 中调整 logging 配置。

常见问题

问题 解决方案
环境变量文件不存在 部署脚本会自动从 .env.example 创建，或手动 cp docker/.env.example docker/.env
前端构建失败 建议在本地构建前端，将 dist 目录上传到 docker/nginx/ 对应目录
容器启动失败 cd docker && docker compose logs [服务名] 查看具体错误
数据库连接失败 确保 .env 中数据库配置正确，MySQL 容器正常运行
端口冲突 修改 .env 中的端口配置，重新部署
MySQL 数据目录权限问题 sudo chown -R 999:999 docker/mysql/data && sudo chmod -R 755 docker/mysql/data

安全建议

  1. 修改默认密码：部署后请修改 .env 中的密码
  2. 保护 .env 文件：已加入 .gitignore，请勿手动提交
  3. 使用正规 SSL 证书：生产中不要使用自签名证书
  4. 限制端口访问：通过防火墙只开放 80/443 端口
  5. 及时更新：定期执行部署脚本获取最新版本

版本更新

./deploy.sh    # 自动拉取最新代码 → 构建新镜像 → 重启容器