使用 NiceGUI 官方 Docker 镜像部署 Python Web 应用docker-compose 实践指南【免费下载链接】niceguiCreate web-based user interfaces with Python. The nice way.项目地址: https://gitcode.com/GitHub_Trending/ni/nicegui本篇技术指南以 NiceGUI 仓库中的 docker_image 示例 为主线完整讲解如何基于官方zauberzeug/nicegui镜像在 Docker 容器中运行 NiceGUI 应用涵盖数据持久化、非 root 用户执行PUID/PGID、SIGTERM 信号透传与优雅关闭、以及 storage secret 环境变量注入等生产级部署要点。读完本文你将掌握一套可直接复制的 Docker 化 NiceGUI 部署方案并能验证容器重启后的数据持久性与关闭行为。示例结构一览docker_image示例的完整文件结构如下examples/docker_image/ ├── README.md # 部署说明本文主体 ├── docker-compose.yml # 容器编排配置 ├── screenshot.webp # 运行界面截图 └── app/ └── main.py # 演示应用文本笔记持久化 优雅关闭回调其中 app/main.py 是一个极简的笔记持久化演示页面提供一个文本输入框输入内容会绑定到app.storage.user从而在服务器端为每个用户会话持久化保存同时注册了app.on_shutdown回调用于验证容器停止时的优雅关闭流程。使用官方镜像与 docker-compose 快速启动官方镜像为 Docker Hub 上的zauberzeug/nicegui示例中的 docker-compose.yml 将其作为唯一服务编排services: nicegui: image: zauberzeug/nicegui:latest ports: - 8080:8080 volumes: - ./app:/app # mounting local app directory environment: - PUID1000 # change this to your user id - PGID1000 # change this to your group id - STORAGE_SECRETchange-this-to-yor-own-private-secret四个关键配置项的作用如下配置项作用说明image: zauberzeug/nicegui:latest指定官方发布镜像使用latest标签即可获得最新发布版生产环境建议固定为具体版本标签以保证可复现性ports: 8080:8080端口映射NiceGUI 默认监听 8080 端口宿主机的 8080 端口被映射到容器内访问 http://localhost:8080 即可打开应用volumes: ./app:/app挂载应用目录将宿主机app目录挂载到容器内/app镜像默认工作目录容器启动后即运行其中的main.pyenvironment: PUID/PGID/STORAGE_SECRET注入环境变量控制容器内运行用户身份与存储加密密钥详见下文各小节由于镜像的工作目录为/app见 release.dockerfile 中的WORKDIR /app其默认CMD为/opt/venv/bin/python main.py挂载目录中的main.py会作为应用入口被自动执行无需额外覆写command。测试步骤按 README 的说明只需两步即可验证整套部署将docker-compose.yml中的PUID、PGID修改为宿主机当前用户的 uid/gid可通过id -u与id -g查询在examples/docker_image目录下执行docker compose up启动后访问 http://localhost:8080在文本框中输入任意内容例如一条待办笔记然后重启容器即可验证数据是否依然存在——这正是下一节数据持久化要解决的问题。如果你不使用 composeREADME 也明确指出可以用docker run加相应参数实现同样效果例如docker run -p 8080:8080 -v $(pwd)/app:/app -e PUID1000 -e PGID1000 \ -e STORAGE_SECRETchange-this-to-yor-own-private-secret zauberzeug/nicegui:latest数据持久化.nicegui目录与app.storage的落盘机制NiceGUI 会自动在应用根目录容器内即/app生成一个.nicegui目录用于保存持久化数据。从源码看这一路径由 nicegui/storage.py 中的Storage.path定义path Path(os.environ.get(NICEGUI_STORAGE_PATH, .nicegui)).resolve()即默认在当前工作目录下创建.nicegui且支持通过NICEGUI_STORAGE_PATH环境变量覆盖。当未配置 Redis 时用户存储通过 FilePersistentDict 落盘为storage-{id}.json文件见 nicegui/storage.py。示例中宿主机app目录被挂载到容器/app因此.nicegui目录会写入宿主机磁盘容器重启后依然保留。README 给出的验证方法是访问 http://localhost:8080输入一些需要存储的数据示例中即文本框里的笔记重启容器CtrlC停止后重新docker compose up再次访问页面确认数据仍然存在。示例应用之所以能记住笔记是因为 app/main.py 将输入框与app.storage.user双向绑定ui.page(/) def index(): ui.textarea(This note is kept between visits) \ .classes(w-96).bind_value(app.storage.user, note)app.storage.user是 NiceGUI 的用户级存储数据保存在服务器端、通过会话 Cookie 标识用户、可在任意时刻修改相关机制见 nicegui/storage.py。这是部署中重启后数据仍在的底层保障。注意使用app.storage.user以及app.storage.browser时必须在ui.run()中提供storage_secret否则运行时会抛出RuntimeError见 nicegui/storage.py这正是下文Storage Secret小节要处理的问题。非 Root 用户执行PUID/PGID 与文件属主容器内的应用以非 root 用户身份运行这一设计与 linuxserver.io 系列镜像的 PUID/PGID 约定一致由环境变量PUID用户 ID与PGID组 ID指定运行时身份。从 docker-entrypoint.sh 可以看到具体实现逻辑从环境变量读取PUID/PGID若未设置或非纯数字则回退为默认值1000检查该 uid/gid 对应的用户/组是否存在不存在则用groupadd/useradd创建将/app目录属主改为该用户chown -R $PUID:$PGID /app保证应用对挂载卷有写权限最后通过setpriv --reuid$PUID --regid$PGID --init-groups切换到目标用户执行容器命令且保持 PID 1 身份注释中说明这与 gosu/su-exec 等价是正确处理信号的前提。带来的直接效果是NiceGUI 运行期间产生的所有文件尤其是.nicegui持久化数据都会带有你配置的 uid/gid而不是 root 属主。这避免了容器里生成的文件在宿主机上无法删除/修改的经典权限问题。README 明确提醒测试前请把docker-compose.yml中的PUID/PGID改成自己宿主机用户的 uid/gidid -u、id -g可查这样容器内创建的文件在宿主机上完全归属于你本人。Docker 信号透传与优雅关闭官方镜像设计为将 Docker 的信号如SIGTERM透传给 NiceGUI 进程从而触发优雅关闭。技术关键在于 docker-entrypoint.sh 的最后一行exec setpriv --reuid$PUID --regid$PGID --init-groups $exec使得入口脚本进程被应用进程替换并保持 PID 1因此容器收到的信号能直接送达 NiceGUIsetpriv在切换用户的同时不丢失这一 PID 1 属性这与 gosu/su-exec 等工具的用途一致。NiceGUI 侧则通过app.on_shutdown注册关闭回调示例 app/main.py 中def handle_shutdown(): print(Shutdown has been initiated!) app.on_shutdown(handle_shutdown)验证方法按 README 的说明运行docker compose up启动容器按CtrlC停止容器Docker 会向容器发送 SIGTERM执行docker compose logs查看日志应能看到Shutdown has been initiated!的输出证明ui.shutdown流程已被触发。这意味着在滚动发布、docker compose down或资源回收等场景下应用有机会执行清理逻辑如关闭数据库连接、刷新缓存、打印审计日志而不会直接被强杀。Storage Secret从环境变量注入会话加密密钥示例中 app/main.py 的最后一行从环境变量读取存储密钥ui.run(storage_secretos.environ[STORAGE_SECRET])该值在 docker-compose.yml 中通过environment注入STORAGE_SECRETchange-this-to-yor-own-private-secret也可以来自 compose 同级目录的.env文件。这个 secret 在 NiceGUI 内部的作用是作为SessionMiddleware的secret_key用于签发和校验会话 Cookie见 nicegui/storage.py它是启用app.storage.user/app.storage.browser的前置条件ui.run()中storage_secret参数默认为None不提供时使用相关存储 API 会直接抛错nicegui/ui_run.py、nicegui/storage.py。两个实操要点务必更换默认值示例中的change-this-to-yor-own-private-secret仅为占位生产环境应替换为足够随机的私有密钥善用.env将STORAGE_SECRET...写入.env文件后compose 会自动读取并注入容器环境变量避免把密钥硬编码进docker-compose.ymlREADME 明确支持这一做法。从镜像构建看运行前提结合仓库中的 release.dockerfile可以进一步明确官方镜像的运行前提基础镜像为python:3.14-slim通过uv安装依赖并EXPOSE 8080入口为/resources/docker-entrypoint.sh即上文分析的 PUID/PGID 与信号处理逻辑默认命令是运行工作目录下的main.py因此只要把包含main.py的应用目录挂载到/app镜像就会以非 root 身份、以 PID 1 进程运行你的应用无需修改镜像本身。这套官方镜像 docker-compose 挂载 环境变量注入的模式是 NiceGUI 官方推荐的容器化部署方式它同时解决了端口暴露、代码热替换重新挂载即更新、数据持久化、文件属主与优雅关闭这五个部署中的高频问题可作为生产环境的起步模板直接套用。【免费下载链接】niceguiCreate web-based user interfaces with Python. The nice way.项目地址: https://gitcode.com/GitHub_Trending/ni/nicegui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 NiceGUI 官方 Docker 镜像部署 Python Web 应用docker-compose 实践指南【免费下载链接】niceguiCreate web-based user interfaces with Python. The nice way.项目地址: https://gitcode.com/GitHub_Trending/ni/nicegui本篇技术指南以 NiceGUI 仓库中的 docker_image 示例 为主线完整讲解如何基于官方zauberzeug/nicegui镜像在 Docker 容器中运行 NiceGUI 应用涵盖数据持久化、非 root 用户执行PUID/PGID、SIGTERM 信号透传与优雅关闭、以及 storage secret 环境变量注入等生产级部署要点。读完本文你将掌握一套可直接复制的 Docker 化 NiceGUI 部署方案并能验证容器重启后的数据持久性与关闭行为。示例结构一览docker_image示例的完整文件结构如下examples/docker_image/ ├── README.md # 部署说明本文主体 ├── docker-compose.yml # 容器编排配置 ├── screenshot.webp # 运行界面截图 └── app/ └── main.py # 演示应用文本笔记持久化 优雅关闭回调其中 app/main.py 是一个极简的笔记持久化演示页面提供一个文本输入框输入内容会绑定到app.storage.user从而在服务器端为每个用户会话持久化保存同时注册了app.on_shutdown回调用于验证容器停止时的优雅关闭流程。使用官方镜像与 docker-compose 快速启动官方镜像为 Docker Hub 上的zauberzeug/nicegui示例中的 docker-compose.yml 将其作为唯一服务编排services: nicegui: image: zauberzeug/nicegui:latest ports: - 8080:8080 volumes: - ./app:/app # mounting local app directory environment: - PUID1000 # change this to your user id - PGID1000 # change this to your group id - STORAGE_SECRETchange-this-to-yor-own-private-secret四个关键配置项的作用如下配置项作用说明image: zauberzeug/nicegui:latest指定官方发布镜像使用latest标签即可获得最新发布版生产环境建议固定为具体版本标签以保证可复现性ports: 8080:8080端口映射NiceGUI 默认监听 8080 端口宿主机的 8080 端口被映射到容器内访问 http://localhost:8080 即可打开应用volumes: ./app:/app挂载应用目录将宿主机app目录挂载到容器内/app镜像默认工作目录容器启动后即运行其中的main.pyenvironment: PUID/PGID/STORAGE_SECRET注入环境变量控制容器内运行用户身份与存储加密密钥详见下文各小节由于镜像的工作目录为/app见 release.dockerfile 中的WORKDIR /app其默认CMD为/opt/venv/bin/python main.py挂载目录中的main.py会作为应用入口被自动执行无需额外覆写command。测试步骤按 README 的说明只需两步即可验证整套部署将docker-compose.yml中的PUID、PGID修改为宿主机当前用户的 uid/gid可通过id -u与id -g查询在examples/docker_image目录下执行docker compose up启动后访问 http://localhost:8080在文本框中输入任意内容例如一条待办笔记然后重启容器即可验证数据是否依然存在——这正是下一节数据持久化要解决的问题。如果你不使用 composeREADME 也明确指出可以用docker run加相应参数实现同样效果例如docker run -p 8080:8080 -v $(pwd)/app:/app -e PUID1000 -e PGID1000 \ -e STORAGE_SECRETchange-this-to-yor-own-private-secret zauberzeug/nicegui:latest数据持久化.nicegui目录与app.storage的落盘机制NiceGUI 会自动在应用根目录容器内即/app生成一个.nicegui目录用于保存持久化数据。从源码看这一路径由 nicegui/storage.py 中的Storage.path定义path Path(os.environ.get(NICEGUI_STORAGE_PATH, .nicegui)).resolve()即默认在当前工作目录下创建.nicegui且支持通过NICEGUI_STORAGE_PATH环境变量覆盖。当未配置 Redis 时用户存储通过 FilePersistentDict 落盘为storage-{id}.json文件见 nicegui/storage.py。示例中宿主机app目录被挂载到容器/app因此.nicegui目录会写入宿主机磁盘容器重启后依然保留。README 给出的验证方法是访问 http://localhost:8080输入一些需要存储的数据示例中即文本框里的笔记重启容器CtrlC停止后重新docker compose up再次访问页面确认数据仍然存在。示例应用之所以能记住笔记是因为 app/main.py 将输入框与app.storage.user双向绑定ui.page(/) def index(): ui.textarea(This note is kept between visits) \ .classes(w-96).bind_value(app.storage.user, note)app.storage.user是 NiceGUI 的用户级存储数据保存在服务器端、通过会话 Cookie 标识用户、可在任意时刻修改相关机制见 nicegui/storage.py。这是部署中重启后数据仍在的底层保障。注意使用app.storage.user以及app.storage.browser时必须在ui.run()中提供storage_secret否则运行时会抛出RuntimeError见 nicegui/storage.py这正是下文Storage Secret小节要处理的问题。非 Root 用户执行PUID/PGID 与文件属主容器内的应用以非 root 用户身份运行这一设计与 linuxserver.io 系列镜像的 PUID/PGID 约定一致由环境变量PUID用户 ID与PGID组 ID指定运行时身份。从 docker-entrypoint.sh 可以看到具体实现逻辑从环境变量读取PUID/PGID若未设置或非纯数字则回退为默认值1000检查该 uid/gid 对应的用户/组是否存在不存在则用groupadd/useradd创建将/app目录属主改为该用户chown -R $PUID:$PGID /app保证应用对挂载卷有写权限最后通过setpriv --reuid$PUID --regid$PGID --init-groups切换到目标用户执行容器命令且保持 PID 1 身份注释中说明这与 gosu/su-exec 等价是正确处理信号的前提。带来的直接效果是NiceGUI 运行期间产生的所有文件尤其是.nicegui持久化数据都会带有你配置的 uid/gid而不是 root 属主。这避免了容器里生成的文件在宿主机上无法删除/修改的经典权限问题。README 明确提醒测试前请把docker-compose.yml中的PUID/PGID改成自己宿主机用户的 uid/gidid -u、id -g可查这样容器内创建的文件在宿主机上完全归属于你本人。Docker 信号透传与优雅关闭官方镜像设计为将 Docker 的信号如SIGTERM透传给 NiceGUI 进程从而触发优雅关闭。技术关键在于 docker-entrypoint.sh 的最后一行exec setpriv --reuid$PUID --regid$PGID --init-groups $exec使得入口脚本进程被应用进程替换并保持 PID 1因此容器收到的信号能直接送达 NiceGUIsetpriv在切换用户的同时不丢失这一 PID 1 属性这与 gosu/su-exec 等工具的用途一致。NiceGUI 侧则通过app.on_shutdown注册关闭回调示例 app/main.py 中def handle_shutdown(): print(Shutdown has been initiated!) app.on_shutdown(handle_shutdown)验证方法按 README 的说明运行docker compose up启动容器按CtrlC停止容器Docker 会向容器发送 SIGTERM执行docker compose logs查看日志应能看到Shutdown has been initiated!的输出证明ui.shutdown流程已被触发。这意味着在滚动发布、docker compose down或资源回收等场景下应用有机会执行清理逻辑如关闭数据库连接、刷新缓存、打印审计日志而不会直接被强杀。Storage Secret从环境变量注入会话加密密钥示例中 app/main.py 的最后一行从环境变量读取存储密钥ui.run(storage_secretos.environ[STORAGE_SECRET])该值在 docker-compose.yml 中通过environment注入STORAGE_SECRETchange-this-to-yor-own-private-secret也可以来自 compose 同级目录的.env文件。这个 secret 在 NiceGUI 内部的作用是作为SessionMiddleware的secret_key用于签发和校验会话 Cookie见 nicegui/storage.py它是启用app.storage.user/app.storage.browser的前置条件ui.run()中storage_secret参数默认为None不提供时使用相关存储 API 会直接抛错nicegui/ui_run.py、nicegui/storage.py。两个实操要点务必更换默认值示例中的change-this-to-yor-own-private-secret仅为占位生产环境应替换为足够随机的私有密钥善用.env将STORAGE_SECRET...写入.env文件后compose 会自动读取并注入容器环境变量避免把密钥硬编码进docker-compose.ymlREADME 明确支持这一做法。从镜像构建看运行前提结合仓库中的 release.dockerfile可以进一步明确官方镜像的运行前提基础镜像为python:3.14-slim通过uv安装依赖并EXPOSE 8080入口为/resources/docker-entrypoint.sh即上文分析的 PUID/PGID 与信号处理逻辑默认命令是运行工作目录下的main.py因此只要把包含main.py的应用目录挂载到/app镜像就会以非 root 身份、以 PID 1 进程运行你的应用无需修改镜像本身。这套官方镜像 docker-compose 挂载 环境变量注入的模式是 NiceGUI 官方推荐的容器化部署方式它同时解决了端口暴露、代码热替换重新挂载即更新、数据持久化、文件属主与优雅关闭这五个部署中的高频问题可作为生产环境的起步模板直接套用。【免费下载链接】niceguiCreate web-based user interfaces with Python. The nice way.项目地址: https://gitcode.com/GitHub_Trending/ni/nicegui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
