一篇按真实生产流程整理的 FastAPI 部署笔记：虚拟环境、Gunicorn/Uvicorn、systemd、Nginx 和健康检查。

Python FastAPI 项目从本地到服务器部署

目标不是把服务跑起来一次，而是让它能稳定重启、可观察、可回滚。

一、服务器准备

建议先使用普通用户部署，避免长期用 root 运行应用。

sudo apt update
sudo apt install -y python3 python3-venv python3-pip nginx git
sudo useradd -r -m -s /usr/sbin/nologin elikapp

项目目录建议放在 `/opt/elik-api`，日志放在 `/var/log/elik-api`，上传文件单独挂载到可备份目录。

二、创建虚拟环境

cd /opt/elik-api
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip wheel
pip install -r requirements.txt

如果项目依赖 MySQL，记得提前配置 `.env`，不要把数据库密码写进代码仓库。

DATABASE_URL=mysql+pymysql://user:password@127.0.0.1:3306/blog?charset=utf8mb4
SECRET_KEY=replace-me
DEBUG=false

三、数据库迁移

source .venv/bin/activate
alembic upgrade head

迁移前先备份数据库。线上不要直接删表重建。

四、systemd 管理服务

[Unit]
Description=elik FastAPI service
After=network.target

[Service]
User=elikapp
WorkingDirectory=/opt/elik-api
EnvironmentFile=/opt/elik-api/.env
ExecStart=/opt/elik-api/.venv/bin/gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 2 -b 127.0.0.1:8000
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

保存到 `/etc/systemd/system/elik-api.service` 后执行：

sudo systemctl daemon-reload
sudo systemctl enable --now elik-api
sudo systemctl status elik-api

五、Nginx 反向代理

server {
    listen 80;
    server_name api.example.com;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}

sudo nginx -t
sudo systemctl reload nginx

六、上线前检查

/docs 在线上应关闭
.env 权限收紧到应用用户可读
上传目录要做备份
反向代理的 client_max_body_size 要符合后台上传需求
systemd 服务重启后应用能自动恢复

七、常用排错命令

journalctl -u elik-api -f
curl -I http://127.0.0.1:8000/api/v1/auth/options
sudo nginx -t

部署完成后，再配置 HTTPS 和定时备份。FastAPI 本身只负责应用逻辑，进程托管、代理、日志和备份才是线上稳定性的关键。