简介这是一份以Docker方式在虚拟机Ubuntu 22.04上部署ERPNext 14的完整操作指南面向需要快速搭建企业资源规划系统的运维人员与开发者。文档详细梳理了从环境准备到容器运行的各个关键环节包括Git安装、Docker与Docker Compose的配置、国内镜像加速器设置以及汉化开箱即用版的部署流程既解释了命令作用也提供了验证方法与排错思路能有效避开国内网络环境下的常见坑点如Docker Hub拉取失败时的镜像加速器配置。文档以VMware虚拟机环境为基础覆盖从系统准备到服务启动的全部步骤。ERPNext 14作为开源ERP系统覆盖财务、销售、采购、库存、项目管理等核心业务借助Docker的灵活部署可随业务增长扩展容器。资源仅包含1个docx文档大小321KB内容紧凑且步骤完整适合边看边操作。已有629人学习对于希望低成本快速上手ERPNext的团队或个人有较高参考价值。1. 浏览器里打不开 http://localhost/80ERPNext14 部署链路最容易翻车的一环用 Docker 在虚拟机里装 ERPNext14最折磨人的不是安装命令报错而是所有步骤都显示成功最后浏览器却打不开系统。镜像拉取列表一长串容器看似也建起来了可 http://localhost/80 要么一直转圈要么白屏要么 502。这个坑之所以折腾人是因为 Docker 部署把软件源、Git、Docker、Compose、容器编排、数据库初始化、端口映射串成了一条长链路任何一环出问题最终都只表现为“打不开”三个字。这篇笔记把整条链路按故障拆开讲从 apt 源报错、镜像拉取失败到容器起不来、端口被占再到访问地址写错每段都给出能直接抄的排查命令和参数说明。新手可以照着命令把环境一步步装对已经装完但打不开页面的熟手也能顺着章节快速定位到具体是哪一环的锅。2. 安装 Docker 阶段报错GPG 密钥、软件源和用户组三个高发点ERPNext14 是跑在 Docker 容器里的所以整个部署的第一道坎是把 Docker 环境装好。很多人在这一步就会卡住而且报错点非常集中添加软件源之后 apt update 报 404 或签名错误、安装 docker-ce 时提示找不到软件包、装完之后普通用户执行 docker 命令又提示权限不够。这三个问题看着不相关根因其实都在于 Ubuntu 22.04 的 apt 机制、GPG 密钥导入方式和用户组刷新逻辑。2.1 添加 Docker 软件源后 apt update 报 404 或签名错误现象是执行sudo add-apt-repository添加 Docker 软件源之后sudo apt update提示类似The repository ... does not have a Release file或is not signed。大多数人第一反应是重试结果反复重试反复报错。这里先看清根因404 大概率是软件源地址里的系统版本写错了签名错误大概率是 GPG 密钥没导入成功或者 Ubuntu 22.04 对旧式密钥导入方式已经不接受了。我在 Ubuntu 22.04 上一般按这个顺序处理先把依赖包装齐再导入密钥最后加源# 更新系统软件包 sudo apt update sudo apt upgrade sudo apt full-upgrade # 安装通过 HTTPS 获取仓库所需的依赖包 sudo apt install apt-transport-https ca-certificates curl software-properties-common # 切换到 root 后导入 Docker 软件源的 GPG 密钥 sudo -i curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/docker-ce.gpg exit # 验证密钥指纹 sudo apt-key fingerprint 0EBFCD880EBFCD88 # 添加软件源$(lsb_release -cs) 在 22.04 下会自动替换为 jammy sudo add-apt-repository deb [archamd64] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable # 再次更新软件包列表 sudo apt update这里的关键点在密钥导入curl从软件源拉取 GPG 公钥gpg --dearmor把公钥从文本格式转换成二进制格式写到/etc/apt/trusted.gpg.d/目录下apt 才会认这个源。之后用apt-key fingerprint 0EBFCD880EBFCD88验证如果你看到的指纹包含0EBFCD88这一段说明密钥已经导入成功。后半句里$(lsb_release -cs)是动态获取当前 Ubuntu 版本的代号22.04 对应 jammy。如果这里被硬编码成 focal 或 bionic软件源地址里找不到对应的目录就会直接 404。2.2 安装 docker-ce 时提示找不到软件包或 containerd 冲突软件源加好之后执行sudo apt install docker-ce docker-ce-cli containerd.io偶尔会碰到E: Unable to locate package docker-ce或者提示 containerd.io 与旧版本冲突。前者几乎都是因为加完源之后没有再次apt updateapt 的软件包索引里还没有 docker-ce 的记录所以找不到这个包。后者多见于机器上装过旧版 containerd 或者 Docker 残留apt 在解析依赖时卡住。先补一次索引更新再安装sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io如果确实报依赖冲突常见做法是先把旧的 containerd 或 docker 相关包删掉再重装sudo apt remove containerd docker docker-engine docker.io sudo apt autoremove sudo apt install docker-ce docker-ce-cli containerd.io注意docker-ce是 Docker 社区版的核心服务docker-ce-cli是命令行工具containerd.io是容器运行时。三个包缺一不可少装任何一个后面执行docker images都可能提示命令存在但服务起不来。装完之后不要急着往下走先看服务状态。2.3 docker 命令提示 permission deniedsudo 执行却正常这是新手最容易困惑的报错docker images提示permission denied while trying to connect to the Docker daemon socket但前面加个sudo又能正常执行。出现这个现象说明 docker 服务本身是好的问题出在权限上。Docker 客户端要和/var/run/docker.sock通信而这个 socket 文件默认属于 root 用户和 docker 组。当前用户不在 docker 组里自然没权限访问。解决方法是把当前用户加入 docker 组然后重新登录让组信息生效# 把当前用户加入 docker 组 sudo usermod -aG docker $USER # 刷新 shell 的权限状态这一步不能省 su - $USER # 验证 docker images这里有个细节值得注意执行完usermod之后如果你直接在当前终端再执行docker images大概率还是报同样的权限错误。因为 shell 启动时已经读取了用户组信息新组的权限要重新登录或者执行su - $USER才会生效。另外$USER是环境变量会自动替换成当前用户名不需要手动改。如果 docker 组本身不存在那说明安装 docker-ce 时哪里出了问题先回到 2.2 检查软件包安装。2.4 验证 Docker 服务状态systemctl 和 --version 双检查装完 Docker 之后很多人直接开跑 ERPNext14结果后面出了问题才回头查 Docker浪费不少时间。我一般会在这一步强制做双验证一看服务状态二看版本号。两个都能通过才继续往下走。sudo systemctl restart docker sudo systemctl status docker sudo systemctl enable docker docker --versionrestart是让 Docker 服务用最新配置重新启动第一次安装后执行一次很有必要status看服务是否处于 running 状态如果这里显示 failed直接看后面的日志信息定位enable是设置开机自启避免虚拟机重启后 Docker 服务还停在那里后面 ERPNext14 的容器全部跟着起不来。docker --version确认客户端程序正常。到这一步Docker 环境才算真正就绪。这一步多花一分钟后面能少踩很多坑。3. 镜像拉取失败与 docker-compose 不可用registry-mirrors 和命令版本的教训Docker 装好了接下来就是拉取 ERPNext14 的镜像。这个环节的报错非常集中最多的是从 Docker Hub 拉取镜像时超时或提示 not found其次是下载 docker-compose 二进制文件不成功、提示 command not found。还有一个很隐蔽的坑是教程里写的docker compose新版插件命令和你实际安装的docker-compose独立二进制命令不是一回事混用时经常报docker: compose is not a docker command。这一章把这三个问题一次说清。3.1 Docker Hub 拉取镜像超时或 not found先改 daemon.json执行docker compose up -d或者手动docker pull时最典型的现象是进度条长时间不动最后报failed to resolve reference ... not found或者直接连接超时。这里先说根因Docker 引擎默认从 Docker Hub 官方 registry 拉取镜像而 Docker Hub 的访问在部分环境里确实慢慢到超时就会表现成“拉不下来”。很多人第一反应是重试但重试多少次都一样。这类问题我是通过配置/etc/docker/daemon.json的镜像加速器解决的也就是给 Docker 引擎加 registry-mirrors。先创建并编辑配置文件# 切换到 root 用户后创建配置文件 touch /etc/docker/daemon.json # 编辑文件粘贴下面的 JSON 内容 vim /etc/docker/daemon.json/etc/docker/daemon.json是 Docker 守护进程的配置文件写入 registry-mirrors 列表后Docker 拉取镜像时会优先尝试这些镜像服务地址而不是直接连 Docker Hub。配置内容如下{ registry-mirrors: [ https://docker.registry.cyou, https://docker-cf.registry.cyou, https://dockercf.jsdelivr.fyi, https://docker.jsdelivr.fyi, https://dockertest.jsdelivr.fyi, https://mirror.aliyuncs.com, https://dockerproxy.com, https://mirror.baidubce.com, https://docker.m.daocloud.io, https://docker.nju.edu.cn, https://docker.mirrors.sjtug.sjtu.edu.cn, https://docker.mirrors.ustc.edu.cn, https://mirror.iscas.ac.cn, https://docker.rainbond.cc ] }配置写完后关键是重启 Docker 让配置真正生效systemctl daemon-reload systemctl restart docker # 验证镜像加速器是否生效 docker info | grep -A 6 Registry Mirrorssystemctl daemon-reload是让 systemd 重新加载 Docker 服务的配置systemctl restart docker是重启 Docker 引擎这两步顺序执行缺一不可。只改文件不重启拉取行为不会变。最后的docker info输出里如果能看到 Registry Mirrors 列表说明加速器已经生效。这里再补一句镜像服务地址有很多单个地址可能出现同步不及时或暂时不可用配置里多放几个是为了让 Docker 按顺序尝试这也是我习惯一次配置多源的原因。3.2 docker-compose command not found下载、权限、软链接三查docker-compose 的问题比较直白执行docker-compose --version时提示 command not found。常见原因有三个一是二进制文件根本没下载成功二是下载成功了但没有执行权限三是文件在/usr/local/bin下但 PATH 环境变量没覆盖到所以系统找不到这个命令。我在 Ubuntu 22.04 上走的完整流程是这样的# 下载 docker-compose 可执行文件 sudo curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予可执行权限 sudo chmod x /usr/local/bin/docker-compose # 建立软链接让任意位置都能直接调用 sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose # 验证版本 docker-compose --versioncurl命令里的$(uname -s)和$(uname -m)会自动替换为当前系统的内核名和硬件架构在 Ubuntu 22.04 的虚拟机上通常是 Linux 和 x86_64拼出来的下载地址就是docker-compose-Linux-x86_64。chmod x是给二进制文件加执行权限少了这步文件在但没法运行。ln -s是把/usr/local/bin/docker-compose软链接到/usr/bin/docker-compose很多 Linux 发行版的/usr/bin默认就在 PATH 里这样在任何目录下都能直接执行。如果curl下载过程中断文件没写全docker-compose --version可能提示Exec format error或者干脆 command not found。遇到这种情况常见做法是换一个下载时段重试或者用资源包里打包好的 docker-compose 二进制离线拷贝到虚拟机的/usr/local/bin目录下再执行chmod x和ln -s效果完全一样。3.3 docker compose 和 docker-compose 混用同一套命令两种写法这是一个特别容易忽视的坑。你按照手册敲docker compose --project-name erpnext_oob -f pwd.yml up -d系统却提示docker: compose is not a docker command。不是命令敲错了而是 Docker Compose 有两种形式新版 Docker 把 Compose 做成了 Docker CLI 的插件调用方式是docker compose而你用上一节方式下载的独立二进制调用方式是docker-compose。命令形式对应版本典型报错使用建议docker composeCompose v2 插件docker: compose is not a docker command需要单独安装 docker-compose-plugindocker-composeCompose v1 独立二进制无此报错用本文 3.2 的安装方式即可docker-compose --version两者都可显示版本无法区分版本类型检查docker compose version是否可用我的处理习惯是既然手册里 ERPNext14 的启动命令用的是docker compose那就在机器上同时把独立二进制也装上两个命令都能用想用哪个写哪个。如果只装了独立二进制把手册里的启动命令改成docker-compose --project-name erpnext_oob -f pwd.yml up -d也能跑命令参数基本一致。关键是别在一条命令里混着写比如docker-compose --project-name xxx -f pwd.yml up -d中途又换成docker compose容易让人误判问题出在环境上。3.4 镜像加速配置后拉取仍然失败按顺序排查三个点配置完 daemon.json 之后如果拉取镜像还是失败我一般按三个点排查。第一用docker info | grep -A 6 Registry Mirrors确认镜像源真的被 Docker 引擎读到了如果输出为空或者还是默认值多半是 daemon.json 没有保存成功或者重启命令没执行。第二单独拉一个小镜像测试比如docker pull hello-world小镜像流量少、速度快如果它也拉不下来说明镜像源整体不可用需要换列表里的其他地址。第三确认 daemon.json 是合法 JSON少一个逗号、多一个花括号Docker 启动时会直接忽略整个文件而且不报错这时候重启 Docker 后docker info里看不到任何镜像源配置。前两个步骤都是命令级别的排查第三步经常是手写 JSON 时的低级语法错误用python3 -m json.tool /etc/docker/daemon.json格式化验证一下最快。4. ERPNext14 容器起不来、数据库连不上pwd.yml 到 localhost:80 之间的黑匣子镜像拉下来了配置文件也写好了接着执行docker compose --project-name erpnext_oob -f pwd.yml up -d输出显示拉取成功、容器创建成功。但真正打开浏览器访问 ERPNext14 的页面要么一直白屏要么 502甚至直接提示连接不上。这个阶段的问题已经从“环境装没装好”变成了“容器编排和初始化有没有走完”排查思路要整个换掉。你需要知道容器是否真正起来了、数据库是否初始化完成、宿主机端口和容器端口映射是否生效以及浏览器地址栏里到底该输入什么。4.1 up -d 之后容器反复重启先看 compose ps 和 logs执行启动命令后屏幕会输出类似Container erpnext-db Created、Container erpnext-web Created这样的信息看起来一切正常。但真正判断有没有起来靠的是docker compose ps而不是看终端输出的最后几行。如果 web 容器反复重启状态列会显示 restarting数据库容器可能显示 unhealthy。这种情况非常常见根因是 web 容器启动时依赖数据库就绪而数据库容器第一次启动要做数据初始化和迁移时间比 web 容器长web 容器等不到数据库响应就开始反复重启。先把容器状态看清楚再定位具体原因# 查看整个项目的容器状态 docker compose --project-name erpnext_oob -f pwd.yml ps # 查看数据库容器的最近日志 docker compose --project-name erpnext_oob -f pwd.yml logs --tail100 db # 查看 web 容器的最近日志 docker compose --project-name erpnext_oob -f pwd.yml logs --tail100 webdocker compose ps里能直接看到每个容器的状态、端口映射和启动时间。如果 db 容器状态是 unhealthy重点看它的日志数据库初始化阶段日志里会持续输出建表语句和迁移进度这是正常现象等它跑完就好。如果 web 容器日志里反复出现连接数据库被拒绝的提示说明数据库还没就绪这时候不要急着去重启容器给数据库初始化留出时间。ERPNext14 的首次初始化可能要几分钟等所有容器状态稳定成 healthy 或者 Up再去浏览器访问。4.2 80 端口被占用Address already in use容器启动时另一类高发报错长这样Error response from daemon: driver failed programming external connectivity on endpoint ... address already in use。翻译过来就是宿主机的 80 端口已经被别的进程占了Docker 没法把容器的 80 端口映射出来。虚拟机上常见占用者是 nginx、apache或者之前部署过的其他服务甚至可能是你上一次启动 ERPNext14 留下的残留容器。先找到谁占用了 80 端口再决定是停掉占用者还是改掉映射端口# 查看 80 端口被哪个进程占用 sudo ss -lntp | grep :80 # 如果占用者是 nginx停掉 nginx 再重启容器 sudo systemctl stop nginx如果不想停掉现有服务另一个办法是改端口映射。打开 pwd.yml找到 web 服务所在的ports段Compose 里端口映射的格式是宿主机端口:容器端口把左边一列改成8080:80保存后重新执行docker compose --project-name erpnext_oob -f pwd.yml up -d。这样容器内部的 80 端口不变宿主机通过 8080 端口访问容器。改完端口后浏览器访问地址也要跟着改成http://localhost:8080这一步容易忘记后面访问不上又回来查容器状态。4.3 浏览器访问 localhost/80 打不开地址写法和初始化顺序两个问题很多人到了最后一步在火狐浏览器里输入安装手册里写的http://localhost/80结果一直打不开。这里有个很反直觉的细节localhost/80里的/80会被浏览器当作路径而不是端口。正确的写法是http://localhost:8080 可以显式写出来也可以不写直接访问http://localhost因为浏览器默认就会访问 80 端口。这个拼写差异是我见过最多的“最后一公里”翻车点。排除了地址写法问题之后如果输入正确地址页面还是白屏或 502就要区分两种情况访问结果含义处理方式页面提示 502 Bad Gatewayweb 容器存活但 ERPNext14 应用还没就绪等待初始化完成看 web 容器日志页面提示连接被拒绝容器没有监听 80 端口或者端口映射没生效看docker compose ps和端口占用页面一直转圈不加载数据库还在做迁移或容器仍未完全启动用 4.1 的日志命令确认进度输入localhost/80无法访问端口写法错误改为http://localhost:80或http://localhost4.4 首次初始化耗时不要一看到白屏就强杀容器ERPNext14 第一次启动时web 容器起来后还要连接数据库、执行数据库迁移、初始化站点这些步骤在容器日志里可以看到明显的时间线。我的习惯是启动完成后等两三分钟再用curl -I http://localhost:80验证如果返回状态码是 502就继续看日志等日志里出现 ERPNext 相关的启动完成提示再刷新浏览器。如果在这个阶段直接docker compose down再重启初始化可能从半途状态重新开始白屏时间反而更长。判断初始化是否完成最可靠的方式是看日志输出而不是反复刷新页面赌运气。5. 避坑Ubuntu 22.04 装 ERPNext14 最常见的五个踩坑记录这一章把我在虚拟机部署 ERPNext14 过程中实际遇到过的五个高频问题记录下来每条都按“现象 → 原因 → 解决”展开。前两条和安装方式有关后三条和运行习惯有关全部经历过一遍之后你对这套部署流程的把握会完整很多。5.1 现象sudo apt update 时出现 apt-key 弃用警告现象是执行sudo apt update时屏幕输出里混着一行明显的警告提示 apt-key 已被弃用建议用trusted.gpg.d目录下的密钥文件替代。环境是 Ubuntu 22.04apt 版本比较新旧教程里apt-key add那套导入方式虽然还能跑但已经进入了弃用警告阶段。原因Ubuntu 22.04 对 GPG 密钥的管理方式变了新规范是把密钥以二进制形式放在/etc/apt/trusted.gpg.d/而不是用apt-key add导入到统一的 keyring 里。解决按照第 2.1 节的方式用gpg --dearmor -o /etc/apt/trusted.gpg.d/docker-ce.gpg导入密钥然后正常执行sudo apt update。警告消失软件源签名验证也正常。从那以后我再看到旧教程里的apt-key命令都会直接跳过。5.2 现象普通用户执行 docker 命令 permission denied加 sudo 就正常现象是坐在虚拟机前敲docker images终端返回permission denied while trying to connect to the Docker daemon socket但同一台机器上sudo docker images能正常输出镜像列表。新手容易误判成 Docker 没装好实际上服务完全正常。原因Docker 守护进程的 socket 文件默认只对 root 和 docker 组开放当前用户不在 docker 组里。解决执行sudo usermod -aG docker $USER把用户加入 docker 组然后执行su - $USER重新加载 shell 环境再执行docker images验证。注意必须重新登录只关掉终端重开不一定生效因为会话里的组信息没有刷新。5.3 现象daemon.json 写好了镜像列表拉取镜像仍然超时现象是按照第 3.1 节写好了 registry-mirrors重启 Docker 后执行docker pull还是超时看docker info又发现 Registry Mirrors 列表为空。原因多数情况下是 daemon.json 文件内容不是合法 JSON。手写 JSON 时少了一个逗号或者多了一个花括号Docker 引擎启动时解析失败直接忽略了整个配置文件而且不打印任何错误。另一种原因是改了文件但只执行了systemctl daemon-reload没有执行systemctl restart docker守护进程还在用旧配置。解决先用python3 -m json.tool /etc/docker/daemon.json验证 JSON 格式能格式化输出说明语法没问题然后按顺序执行systemctl daemon-reload和systemctl restart docker再用docker info | grep -A 6 Registry Mirrors确认镜像源确实被读到了。5.4 现象手册里写 http://localhost/80浏览器怎么都打不开现象是照着安装手册在火狐地址栏输入http://localhost/80回车后页面打不开或者被解析到一个不存在的路径显示 404 或连接失败。原因/80这个写法本身有问题。HTTP 协议里端口是用冒号写的localhost/80会被浏览器解析成域名 localhost 下的路径/80而不是访问 80 端口。解决地址栏改成http://localhost:80或者干脆省略端口直接访问http://localhost因为 HTTP 默认端口就是 80。改完地址后如果还是打不开再回到第 4 章检查容器状态和端口映射。5.5 现象重启虚拟机后 ERPNext14 再也连不上现象是虚拟机关机后重新启动之前能正常访问的 ERPNext14 页面打不开了。执行docker compose ps发现容器状态是 Exited 或者根本不显示。原因Docker 服务没有设置为开机自启虚拟机重启后 Docker 守护进程没有运行所有容器自然跟着停掉。另外容器本身的启动策略默认不是 always所以即使 Docker 服务重新拉起旧容器也不会自动恢复。解决先执行sudo systemctl enable docker设置 Docker 服务开机自启再执行sudo systemctl start docker启动服务。如果希望容器在 Docker 启动后自动恢复需要在 pwd.yml 对应服务的配置里加一行restart: unless-stopped保存后重新docker compose up -d之后每次虚拟机重启容器都会跟着恢复。这个配置对生产环境尤其重要否则断电一次整个系统就失联了。6. 快速定位三分钟判断 ERPNext14 部署卡在哪一环遇到 ERPNext14 打不开不要先怪浏览器也不要反复重装 Docker。我一般按固定的顺序排查从工具层一路查到应用层每一步都有明确命令和判断依据。这套流程走一遍问题基本能定位到具体环节。第一步是确定工具链本身可用。执行docker version和docker-compose --version如果这两条命令报错或输出异常说明 Docker 或 Compose 没装好直接回到第 2 章和第 3 章处理工具链不要继续往后查。第二步是确认 Docker 服务在运行。执行sudo systemctl status docker如果状态不是 running先sudo systemctl start docker再继续。这一步同时确认了开机自启的配置是否生效虚拟机重启后出现的诡异问题大多卡在这一步。第三步是看容器状态。这是判断 ERPNext14 部署在哪一环的核心命令验证命令预期结果说明问题docker compose --project-name erpnext_oob -f pwd.yml ps所有容器状态为 Up 或 healthy容器 restarting 说明依赖没就绪Exited 说明启动失败docker compose --project-name erpnext_oob -f pwd.yml logs --tail100 web日志出现访问地址监听信息日志停在连接数据库失败的循环里说明数据库没初始化完成curl -I http://localhost:80返回 HTTP 状态码 200 或 302返回 502 说明应用未就绪返回 connection refused 说明端口映射有问题sudo ss -lntp | grep :80输出 docker-proxy 监听 80 端口没有输出说明宿主机端口没被绑定检查 pwd.yml 的 ports 段第四步是根据第三步的结果决定动作。容器 restarting 就等初始化查看 db 容器日志确认数据库进度端口映射没生效就检查 pwd.yml 的 ports 写法和宿主机端口占用页面 502 就用curl -I配合 logs 判断是应用层还是网络层的问题。第五步是等一切就绪后再回到浏览器输入正确地址http://localhost:80。这条链路从零开始完整跑一遍大概三分钟比无目的地重装命令要高效得多。从那以后我每次在虚拟机里装 ERPNext14不管前面多顺利都会强制走一遍docker compose ps加logs --tail100的组合确认容器状态再碰浏览器。这套命令和状态判断表也一并整理在资源包里下载后对着执行就行希望帮到你。本文还有配套的精品资源点击获取