如何用 Poznote 搭建自己的笔记系统：Docker 5 分钟部署完全教程（Windows/Linux/macOS 全平台）

Poznote 是一款免费、开源、可自托管的笔记系统，支持富文本、Markdown、任务清单、看板视图与多人协作。本教程带你用 Docker 在 Windows、Linux 和 macOS 上完成部署：只需 3 条命令，5 分钟就能拥有完全属于自己的私有笔记系统，数据全部保存在自己的机器上。

为什么用 Docker 部署 Poznote 自托管笔记

• ✅零环境依赖：不用自己装 PHP、nginx、SQLite，一个 Docker 镜像全部搞定（镜像内部用 supervisor 统一管理服务进程，构建细节见 Dockerfile）。
• ✅全平台通用：官方镜像支持linux/amd64和linux/arm64，Windows / macOS 通过 Docker Desktop 即可运行，树莓派、NAS 等 ARM 设备也支持。
• ✅数据完全自主：所有笔记、附件、备份都保存在你本地的data/目录，更新应用也不会丢数据。
• ✅5 分钟上线：默认端口8040，克隆仓库、拉取镜像、启动容器即可访问。

准备工作：Docker 环境一键装好

装完后验证一下，能打印出版本号就说明环境就绪：

docker --version docker compose version

💡 三个平台的安装流程完全一致，下文命令通用；Windows 请在 PowerShell 中执行。

3 条命令完成 Poznote Docker 部署（最快方法）

第 1 步：克隆仓库并准备配置文件

仓库里直接自带了部署需要的 docker-compose.yml 和环境模板 .env.template，克隆一次即可：

git clone https://gitcode.com/gh_mirrors/po/poznote cd poznote cp .env.template .env # Windows PowerShell 用：copy .env.template .env

第 2 步：拉取镜像并启动容器

docker compose pull docker compose up -d

docker compose.yml会启动两个容器：

首次启动拉取镜像需要几分钟，之后每次启动都是秒级。

第 3 步：验证部署

执行docker compose ps，两个服务状态均为Up（健康检查通过）即部署成功：

docker compose ps docker compose logs -f webserver # 可选：查看启动日志

首次登录：默认账号、密码与端口

浏览器打开：

http://localhost:8040

• 用户名：admin_change_me
• 密码：admin
• 端口：8040（来自.env的HTTP_WEB_PORT）

⚠️登录后第一件事：改掉默认管理员账号名和密码，再去Settings > Admin Tools > User Management管理多用户。

修改 Poznote 访问端口与关键 .env 配置

大多数日常设置都在网页界面里改，.env只用于"部署/运行时"参数。修改后执行docker compose up -d生效即可。完整说明见 .env.template 内的注释。

🔒 端口被占用时，直接把HTTP_WEB_PORT改成别的端口（如8090）再docker compose up -d即可。

如何更新 Poznote：一键升级、数据永不丢失

笔记、附件、备份全部存放在./data目录（对应容器内/var/www/html/data），升级只会替换镜像，不会动这个目录。更新流程：

cd poznote git pull # 获取最新的 docker-compose.yml 与配置模板 docker compose down docker compose pull # 拉取新版本镜像 docker compose up -d

容器启动脚本（docker/init.sh）会在每次启动时初始化目录、应用环境参数，然后由 supervisord 拉起 nginx 与 php-fpm，无需额外操作。

常见部署问题速查清单

遇到报错别慌，90% 的问题都在这张表里（完整版见 docs/TROUBLESHOOTING.md）：

💡 如果你的环境禁止容器内运行 root 用户（如 K8s 受限策略、rootless Podman），Poznote 提供了专门的非 root 镜像：直接使用仓库内的 docker-compose.rootless.yml，并在首次启动前把data目录属主设为1000:1000即可。

部署之后：自托管笔记系统值得马上试的 3 个功能

1️⃣ 任务日历——把任务列表、截止日期汇总到一张日历上，支持"待办 / 重要 / 逾期 / 已完成"状态筛选：

2️⃣ 深色模式与多主题——左下角主题按钮一键切换 Light / Dark / Black / Lavender / Sepia / Terminal 等 6 套内置主题，护眼夜间党友好：

3️⃣ 多人协作与共享——管理员在 User Management 里建账号即可团队共用一个实例；工作区、笔记、文件夹都能共享，支持公开链接、密码保护或指定用户访问。

更多玩法（AI 助手、MCP 服务、Git 同步、Webhooks、Chrome 扩展）可阅读官方简体中文文档 docs/README.zh-cn.md。

总结：你的私有笔记系统已经上线

回看全程，核心就 4 步：

1. git clone仓库并复制.env.template为.env
2. docker compose pull拉取镜像
3. docker compose up -d启动
4. 浏览器访问http://localhost:8040，用admin_change_me/admin登录并改密码

Windows、Linux、macOS 命令完全一致。从打开终端到拥有笔记系统，5 分钟封顶——数据在自己手里，才是真正"强大的笔记，没有负担"。