[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"menus-public":3,"blog-10054":83,"blog-10054-comments":92},[4,15,43,66],{"id":5,"title":6,"link":7,"icon":8,"target":9,"sort_order":10,"is_active":11,"parent_id":12,"created_at":13,"children":14},10001,"首页","\u002F","","_blank",0,true,null,"2026-04-04T12:03:45",[],{"id":16,"title":17,"link":18,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":12,"created_at":21,"children":22},10038,"墨言博客","\u002Fblog","_self",1,"2026-10-30T23:08:14",[23,29,36],{"id":24,"title":25,"link":26,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":16,"created_at":27,"children":28},10039,"技术前沿","\u002Fblog?category=10001","2026-10-30T23:10:46",[],{"id":30,"title":31,"link":32,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":16,"created_at":34,"children":35},10042,"生活随笔","\u002Fblog?category=20007",2,"2026-10-30T23:55:19",[],{"id":37,"title":38,"link":39,"icon":8,"target":19,"sort_order":40,"is_active":11,"parent_id":16,"created_at":41,"children":42},10043,"旅游日记","\u002Fblog?category=20006",3,"2026-10-31T00:00:11",[],{"id":33,"title":44,"link":45,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":12,"created_at":46,"children":47},"新闻中心","\u002Fnews","2026-10-24T19:09:40",[48,54,60],{"id":49,"title":50,"link":51,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":33,"created_at":52,"children":53},10046,"产品动态","\u002Fnews?category=20010","2026-10-31T00:17:38",[],{"id":55,"title":56,"link":57,"icon":8,"target":19,"sort_order":33,"is_active":11,"parent_id":33,"created_at":58,"children":59},10047,"新闻热点","\u002Fnews?category=20009","2026-10-31T00:17:55",[],{"id":61,"title":62,"link":63,"icon":8,"target":19,"sort_order":40,"is_active":11,"parent_id":33,"created_at":64,"children":65},10045,"公司动态","\u002Fnews?category=20008","2026-10-31T00:17:11",[],{"id":67,"title":68,"link":69,"icon":8,"target":19,"sort_order":67,"is_active":11,"parent_id":12,"created_at":46,"children":70},4,"精彩视频","\u002Fvideo",[71,77],{"id":72,"title":73,"link":74,"icon":8,"target":19,"sort_order":10,"is_active":11,"parent_id":67,"created_at":75,"children":76},13,"活动记录","\u002Fvideo?category=6","2026-10-25T21:04:39",[],{"id":78,"title":79,"link":80,"icon":8,"target":19,"sort_order":20,"is_active":11,"parent_id":67,"created_at":81,"children":82},11,"产品展示","\u002Fvideo?category=5","2026-10-25T21:02:59",[],{"id":84,"category_id":5,"title":85,"author":8,"summary":86,"cover":87,"content":88,"tags":8,"seo_title":8,"seo_description":8,"seo_keywords":8,"og_image":8,"views":89,"comment_count":10,"is_top":90,"is_published":11,"created_at":91},10054,"Fastapi服务器uvicron","Uvicorn 是 FastAPI 的默认 ASGI 服务器，在 FastAPI 项目中启动服务本质上就是启动一个 Uvicorn 进程。下面从基础实例出发，逐步拆解命令行用法、编程式用法、核心参数以及开发\u002F生产环境的配置差异。","\u002Fstatic\u002Fuploads\u002Fblogs\u002F1792983466649-546593858.jpg","Uvicorn 是 FastAPI 的默认 ASGI 服务器，在 FastAPI 项目中启动服务本质上就是启动一个 Uvicorn 进程。下面从**基础实例**出发，逐步拆解命令行用法、编程式用法、核心参数以及开发\u002F生产环境的配置差异。\n\n---\n\n## 先准备一个可运行的 FastAPI 实例\n\n新建 `main.py`：\n\n```python\n# main.py\nfrom fastapi import FastAPI\n\napp = FastAPI(title=\"Uvicorn 用法演示\")\n\n\n@app.get(\"\u002F\")\nasync def root():\n    return {\"message\": \"Hello FastAPI + Uvicorn\"}\n\n\n@app.get(\"\u002Fitems\u002F{item_id}\")\nasync def read_item(item_id: int, q: str | None = None):\n    return {\"item_id\": item_id, \"q\": q}\n```\n\n这个 `app` 对象就是 Uvicorn 要加载的 **ASGI 应用**。“`main:app`”的含义是：从 `main` 模块中导入名为 `app` 的对象。\n\n---\n\n## 方式一：命令行启动（最常用）\n\n### 最简启动\n\n```bash\nuvicorn main:app\n```\n\n默认绑定 `127.0.0.1:8000`，仅本机可访问。\n\n### 开发环境：热重载\n\n```bash\nuvicorn main:app --reload\n```\n\n修改 `main.py` 后，服务器会自动重启，无需手动按 `Ctrl+C` 再启动。\n\n### 生产环境：多进程 + 对外开放\n\n```bash\nuvicorn main:app --host 0.0.0.0 --port 8080 --workers 4\n```\n\n`--host 0.0.0.0` 允许外部访问；`--workers 4` 启动 4 个工作进程，充分利用多核 CPU。FastAPI 官方文档也使用同样的命令形式演示多 worker 启动。\n\n### 带常用调优参数的完整示例\n\n```bash\nuvicorn main:app \\\n  --host 0.0.0.0 \\\n  --port 8080 \\\n  --workers 4 \\\n  --loop uvloop \\\n  --limit-concurrency 1000 \\\n  --timeout-keep-alive 10 \\\n  --log-level warning \\\n  --no-access-log\n```\n\n这条命令启用了 `uvloop` 高性能事件循环、限制最大并发连接数为 1000、将 keep-alive 超时设为 10 秒、降低日志级别并关闭访问日志。\n\n---\n\n## 方式二：编程式启动（`uvicorn.run`）\n\n当需要把启动逻辑写在 Python 代码中时，可以使用 `uvicorn.run()`：\n\n```python\n# main.py\nimport uvicorn\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n\n@app.get(\"\u002F\")\nasync def root():\n    return {\"ok\": True}\n\n\nif __name__ == \"__main__\":\n    uvicorn.run(\n        \"main:app\",          # 必须用导入字符串，不能用 app 对象\n        host=\"0.0.0.0\",\n        port=8000,\n        reload=True,          # 开发环境\n        # workers=4,          # 生产环境，不能与 reload 同时使用\n    )\n```\n\n**关键点**：当使用 `reload=True` 或 `workers` 参数时，`uvicorn.run()` 的第一个参数**必须写成导入字符串** `\"main:app\"`，而不能直接传入 `app` 对象；否则热重载和多进程会失效或报错。同时，这行代码必须放在 `if __name__ == \"__main__\":` 保护块内，避免多进程启动时的重复加载问题。\n\n更底层的写法是使用 `uvicorn.Config` + `uvicorn.Server`，适合需要精细控制 Server 生命周期的场景：\n\n```python\nimport uvicorn\n\nif __name__ == \"__main__\":\n    config = uvicorn.Config(\"main:app\", host=\"127.0.0.1\", port=8000, log_level=\"info\")\n    server = uvicorn.Server(config)\n    server.run()\n```\n\n这种写法与 `uvicorn.run()` 等价，但为后续手动调用 `server.serve()` 或嵌入异步环境提供了入口。\n\n---\n\n## 核心参数分类详解\n\n### 应用与网络绑定\n\n| 参数 | 作用 | 关键说明 |\n|---|---|---|\n| `APP`（位置参数） | ASGI 应用路径 | 格式 `模块:变量`，如 `main:app` |\n| `--host` | 绑定地址 | 默认 `127.0.0.1`；`0.0.0.0` 允许外部访问 |\n| `--port` | 端口 | 默认 `8000` |\n| `--uds` | Unix 域套接字 | 如 `--uds \u002Ftmp\u002Fuvicorn.sock`，常用于反向代理场景 |\n\n### 性能与并发\n\n| 参数 | 作用 |\n|---|---|\n| `--workers` \u002F `-w` | 工作进程数，利用多核 CPU |\n| `--loop` | 事件循环实现，Linux\u002FmacOS 上 `uvloop` 性能最佳 |\n| `--limit-concurrency` | 最大并发连接数，超过时返回 503，起到熔断保护作用 |\n| `--limit-max-requests` | 每个进程处理的最大请求数，可用于规避内存泄漏累积 |\n| `--backlog` | 等待连接队列长度，默认 2048，高并发场景可适当调高 |\n\n`--workers` 是生产环境提升吞吐量的核心参数；`--limit-concurrency` 则是在流量突增时保护进程不被压垮的兜底手段。\n\n### 开发调试\n\n| 参数 | 作用 |\n|---|---|\n| `--reload` | 代码变更自动重启 |\n| `--reload-dir` | 限定监控目录，避免日志\u002F静态文件触发频繁重启 |\n| `--reload-include` \u002F `--reload-exclude` | 指定或排除监控的文件模式（需 `watchfiles`） |\n| `--log-level` | 日志级别，开发时可设为 `debug` 查看细节 |\n\n只监控 `.\u002Fapp` 目录的写法：\n\n```bash\nuvicorn main:app --reload --reload-dir .\u002Fapp\n```\n\n这样日志目录、静态资源目录的变动就不会触发不必要的重启。\n\n### 超时与优雅关闭\n\n| 参数 | 默认值 | 作用 |\n|---|---|---|\n| `--timeout-keep-alive` | 5 秒 | Keep-Alive 连接空闲多久后关闭 |\n| `--timeout-graceful-shutdown` | — | 优雅关闭时等待请求处理完成的最长时间 |\n\n生产环境中适当调大 `--timeout-keep-alive` 可以减少连接重建开销，但不宜过大，否则空闲连接会长期占用资源。\n\n### 反向代理与安全\n\n如果 Uvicorn 前面有 Nginx、Traefik 等反向代理，需要加：\n\n```bash\n--proxy-headers\n```\n\n这样才能通过 `X-Forwarded-For` 获取用户的真实 IP，而不是代理服务器的 IP。如果应用部署在子路径下（如 `example.com\u002Fapi\u002Fv1`），还应设置 `--root-path \u002Fapi\u002Fv1`，否则 Swagger UI 等文档路径可能不正确。\n\nUvicorn 自身也支持直接加载 SSL 证书：\n\n```bash\nuvicorn main:app \\\n  --ssl-keyfile .\u002Fkey.pem \\\n  --ssl-certfile .\u002Fcert.pem\n```\n\n但在生产环境中，更常见的做法是 SSL 终止在 Nginx 或负载均衡器上，Uvicorn 只处理 HTTP。\n\n---\n\n## 开发环境 vs 生产环境：配置策略\n\n### 一条必须记住的规则：`--reload` 与 `--workers` 互斥\n\n`--reload` 和 `--workers` 不能同时使用。`--reload` 是单进程带热重载，服务于开发迭代；`--workers` 是多进程无热重载，服务于生产并发。同时使用会导致不可预期的行为。\n\n### 开发环境典型命令\n\n```bash\nuvicorn main:app --reload --log-level debug\n```\n\n### 生产环境典型命令\n\n```bash\nuvicorn main:app \\\n  --host 0.0.0.0 \\\n  --port 8080 \\\n  --workers 4 \\\n  --loop uvloop \\\n  --limit-concurrency 1000 \\\n  --timeout-keep-alive 10 \\\n  --log-level warning \\\n  --no-access-log \\\n  --proxy-headers\n```\n\n### Worker 数量怎么定\n\n一个常见的经验法则是 `(2 × CPU 核心数) + 1`，但这不是硬性规定。实际取值应结合每个请求的 CPU 密集程度、内存占用以及是否使用异步 I\u002FO 来调整。如果应用是纯异步 I\u002FO 密集型，过多的 worker 并不会带来线性收益，反而会增加内存开销。\n\n---\n\n## 进阶：Gunicorn 作为进程管理器\n\nUvicorn 自身可以用 `--workers` 管理多进程，但在更成熟的生产环境中，常采用 **Gunicorn 作为进程管理器 + Uvicorn 作为 ASGI Worker** 的组合，以获得更完善的进程监控、优雅重启和日志管理能力：\n\n```bash\ngunicorn main:app \\\n  -w 4 \\\n  -k uvicorn.workers.UvicornWorker \\\n  -b 0.0.0.0:8000\n```\n\n- `-k uvicorn.workers.UvicornWorker`：指定 Uvicorn 提供的 ASGI worker 类；\n- `-w 4`：4 个 worker 进程；\n- `-b 0.0.0.0:8000`：绑定地址与端口。\n\n需要注意的是，如果已经使用 Gunicorn 管理进程，就**不要再给 Uvicorn 传 `--workers`**，进程数由 Gunicorn 的 `-w` 控制，否则会出现进程管理层级混乱。\n\n---\n\n## 小结\n\nUvicorn 的用法可以按一条主线来理解：**开发用 `--reload`（单进程、自动重启），生产用 `--workers`（多进程、无热重载），两者互斥**。命令行方式适合直接启动和容器 entrypoint，编程式 `uvicorn.run(\"main:app\", ...)` 适合把启动逻辑嵌入项目代码，但必须注意使用导入字符串并放在 `if __name__ == \"__main__\":` 下。在此基础上，根据并发量、代理环境和日志需求，按需叠加 `--limit-concurrency`、`--proxy-headers`、`--timeout-keep-alive` 等调优参数即可。",15,false,"2026-10-26T10:57:48",{"list":93,"total":20,"page":20,"size":99},[94],{"id":95,"blog_id":84,"nickname":96,"content":97,"created_at":98},10013,"admin","这是react框架下，后端服务器FastApi应用","2026-10-26T03:31:34",30]