项目构建

UV安装

忽略安装过程，Windows可参考: Windows 安装 UV

初始项目

D:\OpenSource\Python\DeployDemo>uv --version
uv 0.9.18 (0cee76417 2025-12-16)

D:\OpenSource\Python\DeployDemo>uv python install 3.12
Python 3.12 is already installed

D:\OpenSource\Python\DeployDemo>uv init -p 3.12
Initialized project `deploydemo`

D:\OpenSource\Python\DeployDemo>uv run main.py
Using CPython 3.12.12
Creating virtual environment at: .venv
Hello from deploydemo!

D:\OpenSource\Python\DeployDemo>

uv init -p 3.12 会生成4个文件

deploydemo
├── .python-version //项目使用的 Python 的版本
├── README.md       //空的项目说明文件
├── main.py         //包含一个简单的示例代码。
└── pyproject.toml  //定义项目的元数据，如名称、版本和依赖项。

uv run main.py 后会生成 .venv 目录和 uv.lock文件

deploydemo
├── .venv   //虚拟环境，为项目提供了一个与操作系统和其他项目完全隔离的独立Python运行空间
└── uv.lock //跨平台的锁文件，记录了项目所有直接和间接依赖的精确版本号及校验哈希值。确保了无论在哪台机器上安装，得到的依赖树都完全一致，从而实现可重复构建。

uv.lock 需要提交到git，它是确保团队协作和部署时环境一致性的关键文件

构建 FastAPI

D:\OpenSource\Python\DeployDemo>uv add fastapi --extra standard

--extra standard 表示：安装 FastAPI 定义的名为 standard 的一组可选依赖。

uv add fastapi --extra standard

基本等价于：

uv add "fastapi[standard]"

除了 FastAPI 核心包，还会安装常用功能所需的依赖，例如：

• uvicorn[standard]：运行 ASGI 服务
• fastapi-cli：提供 fastapi dev、fastapi run
• python-multipart：处理表单和文件上传
• jinja2：HTML 模板
• httpx：测试客户端等
• email-validator：邮箱字段校验

不加 --extra standard：

uv add fastapi

只安装 FastAPI 的核心依赖，体积更小，但运行服务等功能可能需要你自行添加依赖。

注意命令中应使用英文空格，不要包含中文逗号 ，。通常开发 FastAPI 项目推荐：

uv add fastapi --extra standard

修改 main.py 代码

from fastapi import FastAPI
import time

app = FastAPI()

@app.get("/")
def read_root() -> dict:
   return {"message": f"Hello, FastAPI with UV!{time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())}"}

本地运行

# 切换到代码目录下，项目中的 \.venv\Lib\site-packages\uvicorn 运行
D:\OpenSource\Python\DeployDemo>uv run uvicorn main:app --reload --host 0.0.0.0 --port 8001
INFO:     Will watch for changes in these directories: ['D:\\OpenSource\\Python\\DeployDemo']
INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
INFO:     Started reloader process [78068] using WatchFiles
INFO:     Started server process [76700]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

• uvicorn ： ASGI（Asynchronous Server Gateway Interface）服务器，用于构建异步 Web 服务，可以理解成 Tomcat、IIS 类似的产品

• main:app ： 前面是文件路径，如果有目录，会写在 uvicorn project.main:app, app是变量名， FastAPI 的实例，app = FastAPI()

• --reload ： 选项的作用是在代码发生变化时自动重新加载应用，以便进行开发和调试。不建议在生产环境中使用，因为它会导致应用在每次请求时重新加载代码，降低性能。

• --host 0.0.0.0 ： 监听本机上的所有网络接，比如多个网卡，如果改成 host 172.16.27.88，那只能通过这个IP地址访问，不能用别的地址访问

• --port 8001 ： 指定端口运行

项目部署

服务器环境安装

安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.local/bin/env
uv --version

创建目录：

# APP 放程序文件
# data 放数据库文件如 SQLite
# config 放配置文件，如：.env
sudo mkdir -p /opt/deploydemo/{app,data,config}
sudo chown -R $USER:$USER /opt/deploydemo
cd /opt/deploydemo

把以下2个文件上传到 /opt/deploydemo：

pyproject.toml
uv.lock

安装 Python 3.12 和依赖：

uv python install 3.12
# 同步操作确保所有项目依赖项已安装并与锁文件（lockfile）保持一致：https://uv.oaix.tech/reference/cli/sync/
uv sync --frozen --no-dev --no-install-project

本地生成 .pyc 发布包

服务器运行