Reflex 单端口 Docker 生产部署实战Caddy 静态前端与后端代理一站式方案【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex本指南以仓库 docker-example/simple-one-port 为蓝本完整讲解如何用单个 Docker 容器、仅暴露一个 HTTP 端口即可把 Reflex 应用以生产模式prod mode跑起来由 Caddy 静态托管前端构建产物并把 API 请求反向代理给后端同时在容器内以本地 Redis 支撑用户状态存储。读完本文你将掌握 simple-one-port 镜像的构建、运行、端口定制、数据持久化方法以及它背后--backend-only、REFLEX_REDIS_URL、REFLEX_API_URL等关键机制的源码级原理可直接落地到 Render、Heroku 等仅支持单端口暴露的应用托管平台。方案概述一个端口三种角色simple-one-port 部署把整个 Reflex 应用收敛进单个容器、单个 HTTP 端口容器内部实际承担了三类职责Caddy 服务器监听8080由$PORT环境变量控制静态托管前端构建产物并把后端专用路径反向代理给 Python 后端Reflex 后端以--env prod --backend-only模式运行只启动 Python 后端进程不再承担前端开发服务器职责本地 Redis以redis://localhost作为状态存储后端为每个用户会话保存 State。与暴露两个端口的 simple-two-port 不同本方案不依赖外部负载均衡器区分前端/后端端口——从容器外部看所有流量都只进8080这一个端口由 Caddy 在内部完成路由分流。这正是文档所强调的适用前提对于只在单个端口上终止 TLS 的平台可以用本容器替代 simple-two-port 示例。为什么适合内存受限环境静态导出替代 Vite 服务器原文档明确指出这种部署方式对内存受限环境尤其友好原因在于它只运行静态前端导出而不是通过 node 运行 Vite 开发/构建服务器。从 Dockerfile 第 30 行可以看到关键步骤RUN reflex export --frontend-only --no-zip mv .web/build/client/* /srv/ rm -rf .web这条命令把前端一次性编译为纯静态文件--no-zip表示不解压 zip 包直接使用导出目录随后移动到/srv目录并删除整个.web目录内含 node_modules 等体积庞大、仅在构建期需要的依赖。最终运行镜像里不再有 node 进程、不再有 Vite dev serverdocker run时只有一个 Caddy 静态文件服务器 一个 Python 后端 一个轻量 redis-server内存占用显著降低。作为对照simple-two-port 方案里3000端口是node server基于优化生产构建8000端口是 Python gunicorn 后端两者都需要常驻进程而本方案把前端进程整个省掉了。构建与运行最小上手路径在项目目录包含requirements.txt、rxconfig.py和应用代码下执行构建docker build -t reflex-simple-one-port .运行并映射端口docker run -p 8080:8080 reflex-simple-one-port端口与 API 地址的定制Dockerfile 第 10-13 行提供了两个构建参数是定制部署的核心入口ARG PORT8080 ARG API_URL ENV PORT$PORT REFLEX_API_URL${API_URL:-http://localhost:$PORT} REFLEX_REDIS_URLredis://localhost PYTHONUNBUFFERED1PORT默认8080。若目标平台要求其他端口例如 Render 期望端口10000通过--build-arg PORT10000覆盖API_URL构建期可选。注释明确说明仅在本地/直连访问时需要设置当使用 TLS 时假定API_URL与前端地址相同因此留空即可REFLEX_API_URL会回退为http://localhost:$PORT。此外PYTHONUNBUFFERED1确保 Python 日志即时输出到容器标准输出便于平台侧收集日志。容器启动流程CMD 逐行解读Dockerfile 第 38-41 行的启动命令集中体现了生产就绪的细节CMD [ -d alembic ] reflex db migrate; \ caddy start \ redis-server --daemonize yes \ exec reflex run --env prod --backend-only自动迁移若项目存在alembic目录说明启用了数据库迁移先执行reflex db migrate应用迁移启动 Caddycaddy start以守护方式启动反向代理启动 Redisredis-server --daemonize yes后台运行本地 Redis启动后端exec reflex run --env prod --backend-only以生产模式、仅后端模式启动 Reflex 服务exec保证信号直达主进程。值得一提的还有第 33 行STOPSIGNAL SIGKILL注释说明这是在 Reflex 正确传递 SIGTERM 到后端之前的临时措施用于保证容器停止时后端进程能被可靠终止避免平台侧出现僵尸进程。Caddy 配置一条流量的内部旅程simple-one-port/Caddyfile 只有十几行却是整个单端口方案的核心路由逻辑:{$PORT} encode gzip backend_routes path /_event/* /ping /_upload /_upload/* handle backend_routes { reverse_proxy localhost:8000 } root * /srv route { try_files {path} {path}/ /404.html file_server }逐段拆解{$PORT}监听端口直接取自环境变量与 Dockerfile 中ENV PORT联动encode gzip对响应启用 gzip 压缩静态资源传输更省带宽后端路由匹配路径匹配/_event/*事件处理端点、/ping健康检查、/_upload与/_upload/*文件上传端点这类请求被反向代理到localhost:8000的 Python 后端前端静态服务其余所有路径以/srv为根目录通过try_files尝试文件、目录、最终回退到404.html由file_server提供静态文件。可以看到Caddy 的存在让前端静态托管 后端代理在单端口内自然分流这也是本方案能够脱离外部负载均衡器独立运行的根本原因。同样的 Caddyfile 也被 production-one-port 复用说明这一路由模式在本仓库中是被验证过的通用做法。无持久化陷阱与数据保留方案原文档特别提醒该容器没有持久化停止后所有数据都会丢失。需要持久化数据库与上传文件时可用**绑定挂载bind mounts或命名卷named volumes**分别挂载数据库目录与uploaded_files目录。例如若应用使用 SQLite 数据库仓库根目录 docs/database/overview.md 中描述了 Reflex 对 SQLite/PostgreSQL 的默认支持与文件上传能力可以这样运行docker run -p 8080:8080 \ -v $(pwd)/data:/app/data \ -v $(pwd)/uploaded_files:/app/uploaded_files \ reflex-simple-one-port生产环境更推荐的替代方案是 production-compose它用独立 Postgres 数据库替代容器内易失存储并为 VPS 场景提供完整编排。若需要多实例横向扩展则每个实例共享一个外部 Redis 才是有状态会话的正确解法。适用场景Render / Heroku 与既有边缘层原文档给出的两个典型使用场景与既有负载均衡器/反向代理配合容器自身不做 TLS 终止由外部边缘层如平台的 LB、CDN统一终止 TLS 后把流量转发到本容器的8080部署到仅支持单端口的简易应用平台如Render、Heroku这类 PaaS——它们通常只暴露一个端口、不允许自定义多端口路由本方案镜像可以直接适配。从仓库整体布局看docker-example/README.md 将本方案定位为导出静态前端、用 Caddy 通过单个 HTTP 端口提供服务与 simple-two-port依赖负载均衡分流双端口、production-composeVPS 全套编排、production-app-platform托管平台后端依赖独立 Redis 与静态前端部署形成四种互补的部署形态按目标平台能力选用即可。升级方向production-one-port 的多阶段构建优化如果你认可单端口架构但希望镜像更小、构建更快仓库还提供了同架构的进阶版 production-one-port。它在概念上与 simple-one-port 完全一致额外具备Python、Reflex、node 依赖的层缓存layer caching先单独COPY requirements.txt安装依赖再拷贝应用代码命中 Docker 缓存层避免每次构建重复安装多阶段构建multi-stagebuilder 阶段编译前端、产出/srv静态文件后最终镜像基于python:3.13-slim只拷贝必要文件COPY --frombuilder /app /app与COPY --frombuilder /srv /srv显著减小最终镜像体积。源码级原理验证--backend-only为何后端可以独立运行Dockerfile 第 41 行使用reflex run --env prod --backend-only。在 reflex/reflex.py 中可以看到--backend-only是reflex run的显式选项其约束逻辑第 525-535 行附近明确了三点--frontend-only与--backend-only不可同时使用--single-port与二者同样互斥该选项会把环境变量REFLEX_BACKEND_ONLY置位第 551 行并在 reflex/assets.py 等处影响资源与页面处理的短路逻辑——这正是前端已由 Caddy 静态托管、后端只需处理事件与 API这一架构在源码层面的落点。REFLEX_REDIS_URLRedis 状态存储的解析规则容器通过REFLEX_REDIS_URLredis://localhost把用户状态指向容器内 Redis。在 reflex/utils/prerequisites.py 的parse_redis_url中可以看到严格的协议校验REFLEX_REDIS_URL必须以redis://、rediss://或unix://开头否则抛出ValueError。同文件第 387-419 行的get_redis/get_redis_sync据此创建异步/同步 Redis 客户端——这就是每个用户的状态由本地 Redis 存储的实现通道。小结与最佳实践simple-one-port 用最小的架构复杂度解决了单端口平台的部署难题要点归纳如下关注点结论暴露端口仅8080$PORT可定制Render 等平台按需改10000前端reflex export --frontend-only静态导出Caddy 托管于/srv后端reflex run --env prod --backend-onlygunicorn/uvicorn 监听8000状态存储容器内 RedisREFLEX_REDIS_URLredis://localhost无持久化TLS由外部负载均衡器/平台边缘层终止容器只收 HTTP内存优势无 node/Vite 进程适合内存受限环境数据持久化用 bind mount / named volume 挂载数据库与 uploaded_files多实例场景改用外部 Redis Postgres见 production-compose对于追求极致镜像体积与构建速度的团队可直接在 production-one-port 基础上迭代对于双端口架构更熟悉的场景可对照 simple-two-port 的负载均衡路由理解两者差异。选择何种形态核心判断标准始终是目标平台能暴露几个端口、是否允许容器内常驻 node 进程、状态是否需要跨实例共享。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考