尧图网站建设 
Reflex 生产环境部署实战基于 Docker Compose Caddy 自动 TLS 的单机部署指南【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex本篇指南以 Reflex 官方仓库中的 production-compose 示例 为核心完整讲解如何在一台独立 VPS 上用 Docker Compose 编排 Caddy 反向代理与 Reflex 后端服务实现「静态前端由 Caddy 直出、后端仅跑 Python 服务、HTTPS 证书自动签发」的生产级单机部署。读完本文你将掌握该示例的全部构建细节、Caddyfile 路由配置、数据持久化方案以及如何叠加 Postgres、Redis 与管理工具组成更健壮的部署栈。一、方案概览为何选择 production-composeReflex 官方在 docker-example 目录下提供了多种 Docker 部署范式production-compose是其中面向「独立 VPS、单应用托管」场景的完整栈方案。它与其他方案的本质区别在于前端静态化应用镜像在构建阶段通过reflex export --frontend-only将前端导出为静态文件交由 Caddy 直接托管运行期不再需要 Node.js自动 TLSCaddy 充当 Web 服务器与反向代理为localhost或环境变量DOMAIN指定的域名自动申请并续期 HTTPS 证书单栈编排一个compose.yaml即可拉起 Web 服务器与后端配合覆盖文件可追加 Postgres、Redis 与管理工具。从架构看这是「静态资源 动态接口分离」的经典模式浏览器请求静态页面时由 Caddy 直接返回只有后端 API 类请求事件处理、上传、健康检查等才会被代理转发到应用容器。由于后端镜像不包含 Node.js 运行时这种部署方式占用内存更少、性能更佳——这是原文档明确指出的优势也是选择该方案的核心动机。二、镜像构建两阶段 Dockerfile 拆解production-compose 的核心构建逻辑位于根目录 Dockerfile采用标准的多阶段构建将「构建产物」与「运行环境」彻底分离。阶段一init —— 导出静态前端基础镜像为python:3.13首先安装uv以加速 Python 依赖引导然后将项目上下文复制到/appFROM python:3.13 as init ARG uv/root/.local/bin/uv ADD --chmod755 https://astral.sh/uv/install.sh /install.sh RUN /install.sh rm /install.sh WORKDIR /app COPY . . RUN mkdir -p /app/data /app/uploaded_files随后在虚拟环境中安装依赖并依次执行 Reflex 的初始化与前端导出ENV VIRTUAL_ENV/app/.venv ENV PATH$VIRTUAL_ENV/bin:$PATH RUN $uv venv RUN $uv pip install -r requirements.txt RUN reflex init RUN reflex export --frontend-only --no-zip这里的reflex export --frontend-only --no-zip是关键一步--frontend-only只导出前端产物后端不参与静态导出--no-zip表示直接输出目录而非压缩包导出结果位于/app/.web/build/client。为节省后端镜像体积阶段末尾将静态文件移出.web目录后重建RUN mv .web/build/client /tmp/client RUN rm -rf .web mkdir -p .web/build RUN mv /tmp/client .web/build/client阶段二slim —— 精简运行镜像最终镜像基于python:3.13-slim只携带虚拟环境与静态产物FROM python:3.13-slim WORKDIR /app RUN adduser --disabled-password --home /app reflex COPY --chownreflex --frominit /app /app RUN apt-get update -y apt-get install -y libpq-dev rm -rf /var/lib/apt/lists/* USER reflex ENV PATH/app/.venv/bin:$PATH PYTHONUNBUFFERED1几个值得注意的实现细节以非 root 用户reflex运行符合最小权限原则libpq-dev是为psycopgPostgres 驱动准备的编译依赖注释明确说明「如果不使用 Postgres 可以跳过」STOPSIGNAL SIGKILL用于规避 Reflex 后端暂未正确传递 SIGTERM 的问题启动命令在容器入口统一处理数据库迁移再以生产模式仅启动后端CMD [ -d alembic ] reflex db migrate; \ exec reflex run --env prod --backend-only--backend-only意味着该容器不负责提供任何前端页面只运行后端事件服务前端完全交给 Caddy。reflex db migrate仅在项目存在alembic目录即启用了数据库迁移时才执行保证每次启动前 schema 与代码一致。三、Web 服务器Caddy 的自动 TLS 与反向代理Caddy 镜像Caddy.Dockerfile 非常简单——基于官方caddy镜像将构建产物local/reflex-app镜像内的静态前端复制到/srv并注入 Caddyfile 配置FROM library/caddy COPY --fromlocal/reflex-app /app/.web/build/client /srv ADD Caddyfile /etc/caddy/Caddyfile注意这里的--fromlocal/reflex-app引用的是 compose 中构建出的本地镜像名见下文 compose 的image: local/reflex-app两阶段镜像间通过该名称衔接。Caddyfile 路由设计Caddyfile 是整条请求链路的枢纽全文如下{$DOMAIN} encode gzip backend_routes path /_event/* /ping /_upload /_upload/* handle backend_routes { reverse_proxy app:8000 } root * /srv route { try_files {path} {path}/ /404.html file_server }逐行解读{$DOMAIN}站点地址由环境变量注入。Caddy 会根据该值自动申请证书localhost则走本地自签证书encode gzip对响应启用 gzip 压缩backend_routes定义了一组「必须转发给后端」的路径匹配器包含/_event/*Reflex 事件处理端点、/ping健康检查、/_upload与/_upload/*文件上传端点。命中后由reverse_proxy app:8000转发到 compose 服务名为app的容器 8000 端口Reflex 后端默认端口root * /srv指定静态资源根目录route块内try_files先尝试精确路径、再尝试目录索引兜底返回404.html最后file_server提供静态文件服务。原文档特别提示如果应用使用了额外的后端 API 路由需要同步把它们追加到backend_routes路径匹配器中否则这些请求会被 Caddy 当作静态资源处理而得不到正确的后端响应。这是自定义该方案时最容易被忽略的一步。四、Compose 编排基础栈与三种启动方式基础 compose.yamlcompose.yaml 定义了两个核心服务服务镜像职责关键配置applocal/reflex-appReflex 后端REFLEX_DB_URL: sqlite:///data/reflex.db挂载db-data、upload-data卷webserverCaddyTLS 终止 静态托管 反向代理暴露443/80端口挂载caddy-data卷depends_on: app关键点REFLEX_DB_URL默认使用 SQLite数据库文件落在/app/data对应命名卷db-dataDOMAIN: ${DOMAIN:-localhost}域名由宿主环境变量注入未设置时回退为localhost——这正是原文档强调「如果不提供 DOMAIN服务将默认 localhost」的代码依据80端口保留用于 ACME HTTP 质询证书签发验证三个命名卷分别持久化数据库db-data、上传文件upload-data与 TLS 证书caddy-data。证书卷尤其重要若不持久化Caddy 每次重建容器都要重新签发证书可能触发速率限制。构建与启动命令构建时必须传入DOMAIN注意不要带http://或https://前缀Caddy 会强制使用 HTTPSDOMAINexample.com docker compose build该命令会同时构建app默认 Dockerfile与webserverCaddy.Dockerfile两个服务。随后启动DOMAINexample.com docker compose up应用即在指定域名以 HTTPS 提供访问。原文档提醒证书签发是自动进行的首次可能耗时几分钟期间请耐心等待或观察 Caddy 日志。数据持久化清单整个栈共使用 4 个命名卷职责划分如下卷名挂载位置持久化内容db-data/app/dataSQLite 数据库文件upload-data/app/uploaded_files用户上传文件caddy-data/root/.caddyTLS 密钥与证书postgres-data/var/lib/postgresql/dataPostgres 数据compose.prod.yaml 引入五、健壮化部署叠加 Postgres 与 Redis原文档指出若要支撑更大流量、让后端以多 worker 运行应使用 compose.prod.yaml 覆盖文件它额外引入了 Postgres 与 RedisDOMAINexample.com docker compose -f compose.yaml -f compose.prod.yaml up -d覆盖文件的核心改动services: db: image: postgres restart: always environment: POSTGRES_PASSWORD: secret redis: image: redis restart: always app: environment: REFLEX_DB_URL: postgresqlpsycopg://postgres:secretdb/postgres REFLEX_REDIS_URL: redis://redis:6379 depends_on: - db - redis两个环境变量的语义可以从源码得到印证REFLEX_DB_URL对应 Reflex 配置中的db_url见 reflex/model.py 中url or conf.db_url的取值逻辑此处切换为postgresqlpsycopg驱动REFLEX_REDIS_URL对应redis_url配置reflex/utils/prerequisites.py 中的parse_redis_url()明确校验该值必须以前缀redis://、rediss://或unix://开头——redis://redis:6379符合规范。Redis 在后端启用多 worker 时承担状态共享与缓存职责。切换数据库后Postgres 使用独立的postgres-data命名卷持久化数据原文档特别说明这一点。注意POSTGRES_PASSWORD: secret是示例值真实生产环境务必替换为强密码并建议通过 compose 的.env文件或密钥管理机制注入。六、管理工具按需启用的运维辅助栈compose.tools.yaml 提供了两个图形化管理工具需与 prod 覆盖文件叠加使用DOMAINexample.com docker compose -f compose.yaml -f compose.prod.yaml -f compose.tools.yaml up -d服务工具访问地址用途adminerAdminerhttp://localhost:8080图形化数据库管理redis-commanderRedis Commanderhttp://localhost:8081Redis 缓存浏览器redis-commander通过REDIS_HOSTSlocal:redis:6379指定要连接的 Redis 实例。原文档明确建议这些服务仅在需要时临时拉起不推荐长期部署——它们面向运维排查场景常驻运行只会增加攻击面与资源占用。七、自定义要点与部署检查清单综合原文档与源码实现部署或改造该方案时应重点检查以下事项追加后端路由应用新增了自定义 API 端点时务必同步更新 Caddyfile 中的backend_routes匹配器环境变量一致性DOMAIN在构建与启动时都应传入虽然 Caddyfile 的{$DOMAIN}在容器运行期读取但保持一致的部署习惯可避免混淆域名不带协议前缀数据库迁移镜像启动命令会检测alembic目录自动执行reflex db migrate更换 Postgres 后需确认psycopg依赖与libpq-dev已就位Redis URL 前缀REFLEX_REDIS_URL仅接受redis://、rediss://、unix://三种前缀源码校验填错将导致启动期解析失败证书续期caddy-data卷务必持久化否则重建容器会触发证书重新签发安全基线将示例中的 Postgres 密码、管理工具暴露端口替换为符合生产要求的配置管理工具仅在需要时启用。八、总结production-compose示例为 Reflex 应用提供了一套开箱即用、可渐进增强的单机生产部署方案两阶段镜像构建保证运行镜像轻量无 Node.jsCaddy 一站式解决静态托管、反向代理与自动 HTTPScompose 覆盖文件机制让「基础栈 → 高可用栈 → 运维栈」的演进只差一条命令。无论是快速上线一个个人项目还是作为更大规模部署的参照样板这份配置都值得直接复用并按上述清单定制。如需对比其他部署形态单端口、双端口、平台托管可继续阅读仓库中的 docker-example 总览 与 production-one-port、simple-two-port 等相邻示例。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Reflex 生产环境部署实战：基于 Docker Compose + Caddy 自动 TLS 的单机部署指南
Reflex 生产环境部署实战基于 Docker Compose Caddy 自动 TLS 的单机部署指南【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex本篇指南以 Reflex 官方仓库中的 production-compose 示例 为核心完整讲解如何在一台独立 VPS 上用 Docker Compose 编排 Caddy 反向代理与 Reflex 后端服务实现「静态前端由 Caddy 直出、后端仅跑 Python 服务、HTTPS 证书自动签发」的生产级单机部署。读完本文你将掌握该示例的全部构建细节、Caddyfile 路由配置、数据持久化方案以及如何叠加 Postgres、Redis 与管理工具组成更健壮的部署栈。一、方案概览为何选择 production-composeReflex 官方在 docker-example 目录下提供了多种 Docker 部署范式production-compose是其中面向「独立 VPS、单应用托管」场景的完整栈方案。它与其他方案的本质区别在于前端静态化应用镜像在构建阶段通过reflex export --frontend-only将前端导出为静态文件交由 Caddy 直接托管运行期不再需要 Node.js自动 TLSCaddy 充当 Web 服务器与反向代理为localhost或环境变量DOMAIN指定的域名自动申请并续期 HTTPS 证书单栈编排一个compose.yaml即可拉起 Web 服务器与后端配合覆盖文件可追加 Postgres、Redis 与管理工具。从架构看这是「静态资源 动态接口分离」的经典模式浏览器请求静态页面时由 Caddy 直接返回只有后端 API 类请求事件处理、上传、健康检查等才会被代理转发到应用容器。由于后端镜像不包含 Node.js 运行时这种部署方式占用内存更少、性能更佳——这是原文档明确指出的优势也是选择该方案的核心动机。二、镜像构建两阶段 Dockerfile 拆解production-compose 的核心构建逻辑位于根目录 Dockerfile采用标准的多阶段构建将「构建产物」与「运行环境」彻底分离。阶段一init —— 导出静态前端基础镜像为python:3.13首先安装uv以加速 Python 依赖引导然后将项目上下文复制到/appFROM python:3.13 as init ARG uv/root/.local/bin/uv ADD --chmod755 https://astral.sh/uv/install.sh /install.sh RUN /install.sh rm /install.sh WORKDIR /app COPY . . RUN mkdir -p /app/data /app/uploaded_files随后在虚拟环境中安装依赖并依次执行 Reflex 的初始化与前端导出ENV VIRTUAL_ENV/app/.venv ENV PATH$VIRTUAL_ENV/bin:$PATH RUN $uv venv RUN $uv pip install -r requirements.txt RUN reflex init RUN reflex export --frontend-only --no-zip这里的reflex export --frontend-only --no-zip是关键一步--frontend-only只导出前端产物后端不参与静态导出--no-zip表示直接输出目录而非压缩包导出结果位于/app/.web/build/client。为节省后端镜像体积阶段末尾将静态文件移出.web目录后重建RUN mv .web/build/client /tmp/client RUN rm -rf .web mkdir -p .web/build RUN mv /tmp/client .web/build/client阶段二slim —— 精简运行镜像最终镜像基于python:3.13-slim只携带虚拟环境与静态产物FROM python:3.13-slim WORKDIR /app RUN adduser --disabled-password --home /app reflex COPY --chownreflex --frominit /app /app RUN apt-get update -y apt-get install -y libpq-dev rm -rf /var/lib/apt/lists/* USER reflex ENV PATH/app/.venv/bin:$PATH PYTHONUNBUFFERED1几个值得注意的实现细节以非 root 用户reflex运行符合最小权限原则libpq-dev是为psycopgPostgres 驱动准备的编译依赖注释明确说明「如果不使用 Postgres 可以跳过」STOPSIGNAL SIGKILL用于规避 Reflex 后端暂未正确传递 SIGTERM 的问题启动命令在容器入口统一处理数据库迁移再以生产模式仅启动后端CMD [ -d alembic ] reflex db migrate; \ exec reflex run --env prod --backend-only--backend-only意味着该容器不负责提供任何前端页面只运行后端事件服务前端完全交给 Caddy。reflex db migrate仅在项目存在alembic目录即启用了数据库迁移时才执行保证每次启动前 schema 与代码一致。三、Web 服务器Caddy 的自动 TLS 与反向代理Caddy 镜像Caddy.Dockerfile 非常简单——基于官方caddy镜像将构建产物local/reflex-app镜像内的静态前端复制到/srv并注入 Caddyfile 配置FROM library/caddy COPY --fromlocal/reflex-app /app/.web/build/client /srv ADD Caddyfile /etc/caddy/Caddyfile注意这里的--fromlocal/reflex-app引用的是 compose 中构建出的本地镜像名见下文 compose 的image: local/reflex-app两阶段镜像间通过该名称衔接。Caddyfile 路由设计Caddyfile 是整条请求链路的枢纽全文如下{$DOMAIN} encode gzip backend_routes path /_event/* /ping /_upload /_upload/* handle backend_routes { reverse_proxy app:8000 } root * /srv route { try_files {path} {path}/ /404.html file_server }逐行解读{$DOMAIN}站点地址由环境变量注入。Caddy 会根据该值自动申请证书localhost则走本地自签证书encode gzip对响应启用 gzip 压缩backend_routes定义了一组「必须转发给后端」的路径匹配器包含/_event/*Reflex 事件处理端点、/ping健康检查、/_upload与/_upload/*文件上传端点。命中后由reverse_proxy app:8000转发到 compose 服务名为app的容器 8000 端口Reflex 后端默认端口root * /srv指定静态资源根目录route块内try_files先尝试精确路径、再尝试目录索引兜底返回404.html最后file_server提供静态文件服务。原文档特别提示如果应用使用了额外的后端 API 路由需要同步把它们追加到backend_routes路径匹配器中否则这些请求会被 Caddy 当作静态资源处理而得不到正确的后端响应。这是自定义该方案时最容易被忽略的一步。四、Compose 编排基础栈与三种启动方式基础 compose.yamlcompose.yaml 定义了两个核心服务服务镜像职责关键配置applocal/reflex-appReflex 后端REFLEX_DB_URL: sqlite:///data/reflex.db挂载db-data、upload-data卷webserverCaddyTLS 终止 静态托管 反向代理暴露443/80端口挂载caddy-data卷depends_on: app关键点REFLEX_DB_URL默认使用 SQLite数据库文件落在/app/data对应命名卷db-dataDOMAIN: ${DOMAIN:-localhost}域名由宿主环境变量注入未设置时回退为localhost——这正是原文档强调「如果不提供 DOMAIN服务将默认 localhost」的代码依据80端口保留用于 ACME HTTP 质询证书签发验证三个命名卷分别持久化数据库db-data、上传文件upload-data与 TLS 证书caddy-data。证书卷尤其重要若不持久化Caddy 每次重建容器都要重新签发证书可能触发速率限制。构建与启动命令构建时必须传入DOMAIN注意不要带http://或https://前缀Caddy 会强制使用 HTTPSDOMAINexample.com docker compose build该命令会同时构建app默认 Dockerfile与webserverCaddy.Dockerfile两个服务。随后启动DOMAINexample.com docker compose up应用即在指定域名以 HTTPS 提供访问。原文档提醒证书签发是自动进行的首次可能耗时几分钟期间请耐心等待或观察 Caddy 日志。数据持久化清单整个栈共使用 4 个命名卷职责划分如下卷名挂载位置持久化内容db-data/app/dataSQLite 数据库文件upload-data/app/uploaded_files用户上传文件caddy-data/root/.caddyTLS 密钥与证书postgres-data/var/lib/postgresql/dataPostgres 数据compose.prod.yaml 引入五、健壮化部署叠加 Postgres 与 Redis原文档指出若要支撑更大流量、让后端以多 worker 运行应使用 compose.prod.yaml 覆盖文件它额外引入了 Postgres 与 RedisDOMAINexample.com docker compose -f compose.yaml -f compose.prod.yaml up -d覆盖文件的核心改动services: db: image: postgres restart: always environment: POSTGRES_PASSWORD: secret redis: image: redis restart: always app: environment: REFLEX_DB_URL: postgresqlpsycopg://postgres:secretdb/postgres REFLEX_REDIS_URL: redis://redis:6379 depends_on: - db - redis两个环境变量的语义可以从源码得到印证REFLEX_DB_URL对应 Reflex 配置中的db_url见 reflex/model.py 中url or conf.db_url的取值逻辑此处切换为postgresqlpsycopg驱动REFLEX_REDIS_URL对应redis_url配置reflex/utils/prerequisites.py 中的parse_redis_url()明确校验该值必须以前缀redis://、rediss://或unix://开头——redis://redis:6379符合规范。Redis 在后端启用多 worker 时承担状态共享与缓存职责。切换数据库后Postgres 使用独立的postgres-data命名卷持久化数据原文档特别说明这一点。注意POSTGRES_PASSWORD: secret是示例值真实生产环境务必替换为强密码并建议通过 compose 的.env文件或密钥管理机制注入。六、管理工具按需启用的运维辅助栈compose.tools.yaml 提供了两个图形化管理工具需与 prod 覆盖文件叠加使用DOMAINexample.com docker compose -f compose.yaml -f compose.prod.yaml -f compose.tools.yaml up -d服务工具访问地址用途adminerAdminerhttp://localhost:8080图形化数据库管理redis-commanderRedis Commanderhttp://localhost:8081Redis 缓存浏览器redis-commander通过REDIS_HOSTSlocal:redis:6379指定要连接的 Redis 实例。原文档明确建议这些服务仅在需要时临时拉起不推荐长期部署——它们面向运维排查场景常驻运行只会增加攻击面与资源占用。七、自定义要点与部署检查清单综合原文档与源码实现部署或改造该方案时应重点检查以下事项追加后端路由应用新增了自定义 API 端点时务必同步更新 Caddyfile 中的backend_routes匹配器环境变量一致性DOMAIN在构建与启动时都应传入虽然 Caddyfile 的{$DOMAIN}在容器运行期读取但保持一致的部署习惯可避免混淆域名不带协议前缀数据库迁移镜像启动命令会检测alembic目录自动执行reflex db migrate更换 Postgres 后需确认psycopg依赖与libpq-dev已就位Redis URL 前缀REFLEX_REDIS_URL仅接受redis://、rediss://、unix://三种前缀源码校验填错将导致启动期解析失败证书续期caddy-data卷务必持久化否则重建容器会触发证书重新签发安全基线将示例中的 Postgres 密码、管理工具暴露端口替换为符合生产要求的配置管理工具仅在需要时启用。八、总结production-compose示例为 Reflex 应用提供了一套开箱即用、可渐进增强的单机生产部署方案两阶段镜像构建保证运行镜像轻量无 Node.jsCaddy 一站式解决静态托管、反向代理与自动 HTTPScompose 覆盖文件机制让「基础栈 → 高可用栈 → 运维栈」的演进只差一条命令。无论是快速上线一个个人项目还是作为更大规模部署的参照样板这份配置都值得直接复用并按上述清单定制。如需对比其他部署形态单端口、双端口、平台托管可继续阅读仓库中的 docker-example 总览 与 production-one-port、simple-two-port 等相邻示例。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考