环境要求

工作目录

统一使用 ~/workdir（即 /home//workdir）作为部署根目录。

Step 1：安装系统依赖（pip/pnpm/MySQL/Redis/Nginx）

# 安装 pip（Ubuntu 强制模式）
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
python3 /tmp/get-pip.py --break-system-packages
# 安装 pnpm
npm install -g pnpm
# 安装 MySQL + Redis + Nginx
sudo apt-get update
sudo apt-get install -y mysql-server redis-server nginx
# 安装 python3-venv（venv 创建必需）
sudo apt-get install -y python3.12-venv
# 启动服务
sudo service mysql start
sudo service redis-server start

Step 2：配置 MySQL 数据库

sudo mysql -e "CREATE DATABASE IF NOT EXISTS fastapiadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER IF NOT EXISTS 'fastapiadmin'@'localhost' IDENTIFIED BY 'fastapiadmin123';"
sudo mysql -e "GRANT ALL PRIVILEGES ON fastapiadmin.* TO 'fastapiadmin'@'localhost'; FLUSH PRIVILEGES;"

Step 3：克隆代码

mkdir -p ~/workdir && cd ~/workdir
git clone https://gitee.com/fastapiadmin/FastapiAdmin.git
git clone https://gitee.com/fastapiadmin/FastDocs.git

Step 4：后端初始化

cd ~/workdir/FastapiAdmin/backend
# 创建虚拟环境
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
# 配置环境变量
cp env/.env.dev.example env/.env.dev
# 编辑 env/.env.dev，修改：
#   DATABASE_USER = "fastapiadmin"
#   DATABASE_PASSWORD = "fastapiadmin123"
#   REDIS_PASSWORD = ""（无密码则留空）
# 生成并执行迁移
./venv/bin/python main.py revision --env=dev
./venv/bin/python main.py upgrade --env=dev

Step 5：前端构建

cd ~/workdir/FastapiAdmin/frontend
# 安装依赖
pnpm install
# 创建生产环境配置
cat > .env.production << 'EOF'
VITE_APP_ENV=production
VITE_APP_TITLE=FastapiAdmin
VITE_API_BASE_URL=http://
VITE_APP_BASE_API=/api/v1
VITE_TIMEOUT=10000
VITE_APP_WS_ENDPOINT=ws://
EOF
# 构建
pnpm run build

Step 6：Nginx 配置（关键）

Nginx 配置源码位于 ~/workdir/FastapiAdmin/devops/nginx/nginx.conf，部署时复制到 /etc/nginx/nginx.conf。

6.1 生成自签名 SSL 证书

sudo mkdir -p /etc/nginx/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/server.key -out /etc/nginx/ssl/server.pem \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=FastapiAdmin/OU=Dev/CN=localhost"
sudo chmod 600 /etc/nginx/ssl/server.key

6.2 Nginx 配置模板

⚠️ 关键修复：原配置中 alias + try_files 组合会导致重定向循环。必须用精确匹配 location = /web/index.html 作为内部 fallback，而非 named location 或路径重写。

编辑 ~/workdir/FastapiAdmin/devops/nginx/nginx.conf，替换 location /web 部分：

# HTTP server块
server {
    listen 80;
    server_name service.fastapiadmin.com;
    location = /web {
        return 301 /web/;
    }
    location /web/ {
        alias /usr/share/nginx/html/frontend/;
        index index.html;
        try_files $uri $uri/ /web_fallback.html;
    }
    location = /web_fallback.html {
        internal;
        alias /usr/share/nginx/html/frontend/index.html;
    }
    location /api/v1 {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_pass http://127.0.0.1:8001;
    }
}

6.3 部署 Nginx 配置

sudo cp ~/workdir/FastapiAdmin/devops/nginx/nginx.conf /etc/nginx/nginx.conf
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo nginx

Step 7：启动后端服务

cd ~/workdir/FastapiAdmin/backend
./venv/bin/python main.py run --env=dev &

宿主机访问

WSL2 IP 不固定，每次重启后可能变化。获取方式：

hostname -I | awk '{print $1}'

宿主机 Windows 浏览器访问：

• 前端：http:///web/
• API 文档：http:///api/v1/docs

💡 部署后如果 WSL2 IP 变化，只需更新 Nginx 中 .env.production 的 VITE_API_BASE_URL 并重建前端即可。

故障排查

详见 references/troubleshooting.md。

快速命令汇总

# 一键启动
cd ~/workdir/FastapiAdmin/backend && ./venv/bin/python main.py run --env=dev
# 查看 WSL2 IP
hostname -I | awk '{print $1}'
# Nginx 配置测试与重载
sudo nginx -t && sudo nginx -s reload
# 查看 Nginx 错误日志
sudo tail /var/log/nginx/error.log