Odoo 保姆级部署教程：开源全栈 ERP 与业务应用套件，Docker 一键起

本文所有命令与配置均照搬 Odoo 官方仓库 README（github.com/odoo/odoo）、官方安装文档《Installing Odoo》（www.odoo.com/documentation/master/administration/install/install.html）与 Docker 官方镜像文档（hub.docker.com/_/odoo），未作任何改动与发挥。信息核验日期：2026-11-01。

一、项目介绍

Odoo（前身为 OpenERP）是一套用 Python 编写的、基于 Web 的开源业务应用套件。官方 README 对其定位是"a suite of web based open source business apps"（一套基于 Web 的开源商业应用），其应用覆盖开源 CRM、网站构建器（Website Builder）、电子商务（eCommerce）、仓库管理（Warehouse Management）、项目管理、账单与会计（Billing & Accounting）、零售收银（Point of Sale）、人力资源（Human Resources）、营销与制造（Manufacturing）等几乎全部企业经营场景。这些应用既可单独使用，也能无缝集成，从而构成一套功能完整的开源 ERP。

Odoo 社区版（Community Edition）对所有人免费开放，企业版（Enterprise Edition）为 Odoo S.A. 付费客户与合作伙伴提供。项目在 GitHub（odoo/odoo）持续活跃维护，官方提供 nightly 构建、Docker 官方镜像（odoo，Docker Hub 上 5000 万+ 下载），支持 amd64、arm64v8、ppc64le 架构。按官方 Docker 文档，Odoo 是"世界上安装量最大的商业软件"，全球有数百万用户从小型公司到 30 万人规模的大型企业使用。

二、功能拆解

按官方 README，Odoo 主应用（Apps）包括：

功能模块	说明
开源 CRM	客户关系管理，销售漏斗与线索跟进
网站构建器 Website Builder	可视化搭建企业官网/落地页
电子商务 eCommerce	在线商城与订单管理
仓库管理 Inventory	库存、出入库与仓储作业
项目管理 Project	任务、看板与进度跟踪
账单与会计 Accounting	发票、对账与财务核算
零售收银 Point of Sale	门店 POS 收银终端
人力资源 HR	员工、考勤与薪酬
营销 Marketing	邮件营销与社媒投放
制造 Manufacturing	生产工单与物料清单

官方强调：这些应用可独立使用，安装多个应用后即整合为一套全功能 ERP。

三、官方/GitHub 链接

GitHub 仓库：https://github.com/odoo/odoo
官方文档（安装指南）：https://www.odoo.com/documentation/master/administration/install/install.html
官方网站：https://www.odoo.com/
Docker 官方镜像：https://hub.docker.com/_/odoo
nightly 服务器：https://nightly.odoo.com/
在线演示/试用：https://www.odoo.com/trial （官方提供无需安装的在线 demo 实例）

四、环境要求

官方提供多种安装方式（在线版、打包安装器、源码安装、Docker）。本教程以官方 Docker 方式为主（最适合零基础一键复现），并附官方源码启动方式要点。

前置依赖： 已安装 Docker 与 Docker Compose（docker compose 插件）。
数据库： Odoo 必须使用 PostgreSQL（官方文档要求 PostgreSQL 12.0 及以上；Docker 官方镜像文档使用 postgres:15）。
端口： Odoo Web 默认监听 8069；PostgreSQL 容器内部 5432，通常不对宿主暴露。
操作系统： 官方打包安装器支持 Windows、Debian/Ubuntu、Fedora/CentOS/RHEL；Docker 镜像支持 amd64/arm64v8/ppc64le。
Python（源码方式）： 官方文档要求 Python 3.8 及以上。
硬件： 官方文档未给出最低硬件指标；个人/小团队入门建议至少 2 核 CPU、4GB 内存。

五、部署步骤

方式 A：Docker Compose 部署（官方 Docker 文档示例，推荐）

步骤 1：创建部署目录并进入

mkdir odoo && cd odoo

逐段解释：mkdir odoo 创建 odoo 目录；cd odoo 进入。后续 compose 文件与数据都放在这里。

预期输出参考： 命令成功，无输出。

步骤 2：创建官方 compose.yaml

官方 Docker 文档给出的"最简单的 compose.yaml"原文如下，粘贴到 compose.yaml：

services:
  web:
    image: odoo:17.0
    depends_on:
      - db
    ports:
      - "8069:8069"
  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_PASSWORD=odoo
      - POSTGRES_USER=odoo

逐段解释：services.web 是 Odoo 应用服务，image: odoo:17.0 使用官方 17.0 镜像（官方文档原文示例标签；也可换 18.0、19.0、20.0 或 latest，见 Docker Hub 支持标签列表）；depends_on: - db 表示依赖 db 服务先启动；ports: "8069:8069" 把宿主 8069 映射到容器 8069；services.db 是 PostgreSQL 数据库服务，image: postgres:15 使用 PostgreSQL 15；三个环境变量分别设定默认数据库名、数据库密码、数据库用户。官方文档说明：Odoo 容器会用与 POSTGRES_USER/POSTGRES_PASSWORD 相同的账号连接数据库。

步骤 3：后台启动

docker compose up -d

逐段解释：docker compose up 依据 compose.yaml 创建并启动 web 与 db 两个容器；-d 后台运行。

预期输出参考： 出现 [+] Running 3/3、Pulling db ...、Container odoo-db-1 Created、Container odoo-web-1 Started 之类日志，最终回到命令行。

步骤 4：确认容器状态

docker compose ps

逐段解释：列出本 compose 项目的容器状态，Up 表示运行中。

预期输出参考： web 与 db 两行均为 Up，web 暴露 0.0.0.0:8069->8069/tcp。

方式 B：命令行 docker run（官方 Docker 文档）

如需更细粒度控制，官方文档给出的两步法：

命令 1：docker run -d -e POSTGRES_USER=odoo -e POSTGRES_PASSWORD=odoo -e POSTGRES_DB=postgres --name db postgres:15

逐段解释：docker run -d 后台运行 PostgreSQL 容器；-e POSTGRES_USER=odoo -e POSTGRES_PASSWORD=odoo -e POSTGRES_DB=postgres 设定数据库用户、密码、默认库；--name db 固定容器名为 db——官方文档特别强调"运行 Postgres 的容器别名必须是 db，Odoo 才能连上数据库"；postgres:15 镜像。

执行成功后预期输出参考： 输出一串容器 ID，PostgreSQL 首次初始化日志。

命令 2：docker run -v odoo-data:/var/lib/odoo -d -p 8069:8069 --name odoo --link db:db -t odoo

逐段解释：-v odoo-data:/var/lib/odoo 用命名卷把 Odoo 文件存储（filestore）持久化到容器外（官方文档明确：不加这个卷，容器删除后附件文件会丢失）；-p 8069:8069 映射 Web 端口；--name odoo 容器名；--link db:db 连接名为 db 的 Postgres 容器；-t odoo 使用官方镜像。

执行成功后预期输出参考： 输出容器 ID，浏览器随后可访问 8069。

方式 C：源码运行（官方安装文档 Running Odoo）

适合开发者。官方文档原文命令（以 Linux 为例）：

git clone https://github.com/odoo/odoo.git
cd odoo
pip3 install setuptools wheel
pip3 install -r requirements.txt
python3 odoo-bin --addons-path=addons -d mydb

逐段解释：git clone 克隆社区版源码；pip3 install -r requirements.txt 安装 Python 依赖（官方要求 Python 3.8+，并建议用 virtualenv 隔离）；odoo-bin 是 Odoo 命令行入口，--addons-path=addons 指定插件路径，-d mydb 指定要连接/创建的 PostgreSQL 数据库名。官方文档提示还需先装好 PostgreSQL（12.0+）并创建一个非 postgres 的数据库用户（Odoo 禁止直接用 postgres 超级用户连接）。

预期输出参考： 启动后出现 INFO 日志 odoo.modules.loading: Modules loaded.，随后可访问 http://localhost:8069。

六、配置参数详解

1. Docker 环境变量（官方 Docker 文档 Environment Variables 一节）：

变量	默认值	说明
HOST	`db`	PostgreSQL 服务器地址；用 Postgres 容器时填容器名
PORT	`5432`	PostgreSQL 监听端口
USER	`odoo`	连接数据库用的 Postgres 角色名，需与 POSTGRES_USER 一致
PASSWORD	`odoo`	上述角色密码，需与 POSTGRES_PASSWORD 一致

官方 compose 也给出自定义凭据示例：web 服务加 environment: HOST=mydb / USER=odoo / PASSWORD=myodoo，db 服务对应 POSTGRES_PASSWORD=myodoo。

2. 自定义配置文件（官方文档）： Odoo 默认配置文件位于容器内 /etc/odoo/odoo.conf。可用卷挂载覆盖：

docker run -v /path/to/config:/etc/odoo -p 8069:8069 --name odoo --link db:db -t odoo

逐段解释：把宿主 /path/to/config 目录挂载到容器 /etc/odoo，容器启动时读取其中的 odoo.conf。官方文档要求使用其提供的配置模板来写自定义配置。

3. 内联命令行参数（官方文档）： 容器内 Odoo 参数须放在 -- 之后，例如：

docker run -p 8069:8069 --name odoo --link db:db -t odoo -- --db-filter=odoo_db_.*

逐段解释：-- 之后的 --db-filter=odoo_db_.* 是 Odoo 自身参数，限制只匹配名称以 odoo_db_ 开头的数据库。

4. 挂载自定义插件（官方文档）： 官方约定把第三方 addons 挂载到容器 /mnt/extra-addons：

docker run -v /path/to/addons:/mnt/extra-addons -p 8069:8069 --name odoo --link db:db -t odoo

七、启动与运维

启动 / 停止（官方 Docker 文档）： compose 方式 docker compose up -d 启动、docker compose down 停止；单容器方式官方原文 docker stop odoo 与 docker start -a odoo（-a 附加并观察日志）。
查看日志： docker compose logs -f web 跟踪 Odoo 容器日志。
开机自启： 官方未在文档中提供 Odoo 专用 systemd 配置；如需容器随 Docker 守护进程自启，可使用 Docker 平台通用的 restart 策略（在 compose 服务中加 restart: always，属 Docker 原生能力）。
修改端口： 官方「Run multiple Odoo instances」一节展示了端口自由映射，例如 docker run -p 8070:8069 ...、-p 8071:8069 ...。官方同时提示：宿主与容器端口不一致时，需在 Odoo 后台 Settings -> Parameters -> System Parameters 中把 web.base.url 改为实际地址端口。
数据持久化： 官方明确要求 Odoo filestore 用命名卷 /var/lib/odoo 持久化，PostgreSQL 用命名卷 /var/lib/postgresql/data 持久化（官方最后一个 compose 示例同时声明 odoo-web-data 与 odoo-db-data 两个命名卷）。
重启依赖说明（官方文档）： PostgreSQL 容器重启后，关联的 Odoo 容器也必须一并重启，因为容器链接地址会变化；重启 Postgres 不会损坏已建数据库。

八、实操验证

浏览器访问 http://服务器IP:8069（源码方式为 http://localhost:8069）。
首次进入会看到 Odoo 数据库管理/创建页面（Select a database）。按官方安装文档：服务器启动打印 odoo.modules.loading: Modules loaded. 后，即可登录自有的 Odoo 数据库。
默认管理员账号（官方文档 Running Odoo 一节原文）： 邮箱（Email）填 admin，密码（Password）填 admin，即可登录。
登录后进入应用仪表盘（Apps），搜索并安装第一个应用（如 CRM 或 Website），安装完成后左侧菜单出现对应模块，即部署成功。
验证数据持久化：执行 docker compose down && docker compose up -d 后刷新浏览器，已安装的应用与登录状态保留（因使用了命名卷）。

登录与安全（重要）

官方默认账号密码： 官方安装文档原文——登录时 Email 用 admin、Password 用 admin。这是 Odoo 全新数据库的初始超级管理员账号。
登录地址： http://服务器IP:8069（首次为数据库选择/创建页面，之后为登录页）。
首次登录修改密码： 登录后右上角用户头像 →「Preferences / 我的资料」→ 修改密码（Change Password）。
密码重置： 在登录页若开启了多数据库管理，可用 master 密码（admin_passwd，配置文件 /etc/odoo/odoo.conf 中设置）进入数据库管理；忘记 admin 密码时，可在数据库层面重置——官方未在 README 提供一键重置命令，常规做法是进入"设置→用户"由其他管理员重置，或借助 PostgreSQL 数据库直接更新（操作前务必备份）。
密码/配置存放位置： Web 管理员密码以哈希存于 PostgreSQL 数据库中；数据库连接凭据在容器环境变量 USER/PASSWORD 或 /etc/odoo/odoo.conf 中。
安全提醒：部署完成后必须立即把默认的 admin/admin 改为强密码；公网部署务必修改数据库默认密码（官方 compose 示例中的 POSTGRES_PASSWORD=odoo 仅为演示值），并关注官方安全披露页 https://www.odoo.com/security-report 。

九、故障排查

案例 1：Odoo 容器无法连接数据库（could not connect to server / connection refused）

报错原文（常见形式）：could not connect to server: Connection refused ... Is the server running on host "db" and accepting TCP/IP connections on port 5432?
报错原因：官方 Docker 文档明确要求"运行 Postgres 的容器别名必须是 db"，Odoo 默认 HOST=db；若 db 容器未先启动、名字不是 db，或依赖关系缺失，连接即失败。
分步解决：① 确认 db 容器名是 db：docker ps 查看；② 用 compose 的 depends_on: - db 或命令行的 --link db:db 保证先起数据库；③ 检查 Odoo 环境变量 USER/PASSWORD 与 db 容器 POSTGRES_USER/POSTGRES_PASSWORD 完全一致；④ docker compose logs db 看数据库是否初始化完成。

案例 2：容器删除后附件/文件丢失

报错现象：重建 Odoo 容器后，历史附件、用户上传文件全部消失。
报错原因：官方文档明确警告——不加卷时"odoo filestore created inside the container. If the container is removed, the filestore is lost"。
分步解决：按官方做法加命名卷 -v odoo-data:/var/lib/odoo（compose 中声明 odoo-web-data:/var/lib/odoo）；PostgreSQL 同样加 -v odoo-db:/var/lib/postgresql/data。重建容器时复用同名卷即可恢复数据。

案例 3：端口不一致导致邮件/报表链接错误

报错现象：把端口映射改成 8070:8069 后，发出的邮件或 PDF 报表里的链接仍指向 8069 或 localhost。
报错原因：官方文档「Run multiple Odoo instances」一节明确说明——宿主与容器端口不同时，必须在 Odoo 内设置 web.base.url。
分步解决：① 用管理员进入 Settings -> Parameters -> System Parameters（需开启开发者/技术特性）；② 把 web.base.url 改为实际访问地址（如 http://你的域名:8070）；③ 刷新页面生效。

案例 4：源码启动提示 Python 版本过低或依赖缺失

报错原文（常见形式）：This version of Odoo requires Python >= 3.8 或 ModuleNotFoundError: No module named 'xxx'。
报错原因：官方文档要求 Python 3.8+，且依赖需按 requirements.txt 安装；wkhtmltopdf 必须手动安装 0.12.5 版本（官方警告 pip 装不到）。
分步解决：① python3 --version 确认 ≥3.8；② 在隔离环境执行 pip3 install -r requirements.txt；③ 按官方 wiki 安装 wkhtmltopdf 0.12.5；④ 数据库用户需非 postgres：sudo -u postgres createuser -s $USER。

十、升级、回滚与卸载

升级（官方 Docker 文档 How to upgrade this image 一节）： Odoo 镜像每晚自动构建更新同大版本。官方升级命令基于命名卷/旧容器迁移 filestore：

docker run --volumes-from old-odoo -p 8070:8069 --name new-odoo --link db:db -t odoo

逐段解释：--volumes-from old-odoo 继承旧容器 old-odoo 的文件存储卷，把旧附件带入新容器 new-odoo。官方特别说明：Odoo 16.0+ 使用 filestore（位于 /var/lib/odoo/filestore/），升级到同大版本最新镜像直接重拉即可；跨大版本升级需要官方迁移脚本，复杂得多，应参考官方 Odoo Upgrade 页面，勿自行跨大版本升级。

compose 方式升级： 修改 compose.yaml 中 image: odoo:17.0 为目标版本标签后 docker compose pull && docker compose up -d。

回滚： 官方未提供一键回滚命令；可将 compose.yaml / docker run 的镜像标签改回旧大版本（如 odoo:16.0）后重新创建容器，数据库卷保留即可读取（跨大版本回滚同样需官方迁移工具评估）。

卸载： docker compose down 停止并移除容器。彻底清理需删除命名卷（此操作永久删除全部业务数据，务必先备份 PostgreSQL 与 filestore）：docker volume rm odoo-web-data odoo-db-data，并删除镜像 docker rmi odoo postgres。源码方式删除源码目录与 PostgreSQL 数据库即可。

十一、商用许可合规说明

许可证：LGPL v3（GNU Lesser General Public License v3）。官方 Docker Hub 镜像文档明确：Odoo "released under the LGPL license"；社区版代码仓库 LICENSE 文件指向 COPYRIGHT 与 LGPL-3.0。
LGPL-3 允许自由使用、修改与商用（包括在自托管 ERP 场景中免费使用社区版全部模块），但分发修改后的库/衍生作品时须保留版权声明、开源相应修改部分，并允许用户可替换该库。
注意区分： 社区版（Community）免费开源；企业版（Enterprise）模块为 Odoo S.A. 专有，仅付费客户/合作伙伴可获取代码，不得未经授权挂载使用。
商用自托管社区版无需付费授权；如需 SLA、官方支持与企业版模块，可向 Odoo S.A. 购买企业订阅。