第四十九章 Odoo 环境部署（Ubuntu / Windows / macOS）

篇别：第十七篇 环境部署

本章学习目标

• 能在 Ubuntu LTS 上完成 PostgreSQL + Python 虚拟环境 + 源码 Odoo 的 从零安装 与 首次建库。
• 能在 Windows 上选择 WSL2（推荐） 或 原生 Python 路径，并规避 常见编译/编码坑。
• 能在 macOS（Apple Silicon / Intel） 上通过 Homebrew 搭建 与生产接近 的开发库。
• 理解 与第四十二章的分工：本章 按操作系统给命令级流程；odoo.conf、Nginx、worker 等 运行参数与生产架构 以 第四十二章 为纲。
• 能完成 QWeb → PDF 所需的 系统级依赖（wkhtmltopdf / 引擎版本、字体），并会做 命令行与界面验证、常见乱码与超时排障（与 第十九章 §19.2 衔接）。

导读：先对齐版本再动手

1. 以官方为准：Python 次版本、PostgreSQL 最低版本、依赖列表 以你检出的 odoo/requirements.txt 与 Source install 为准；下表为 常见组合（2026 年前后），升级时请 重读仓库 README.md。
2. 社区版 vs 企业版：企业版 为 独立 addons 目录；addons_path 须 同时包含 community + enterprise（许可与订阅自行合规）。
3. 开发 vs 生产：本章默认 单机开发/沙箱；生产 请叠加 第四十二章（反向代理、workers、备份、日志轮转）。
4. 报表 PDF：report_type=qweb-pdf 依赖 服务端 PDF 引擎（历史上多为 wkhtmltopdf；具体以 Odoo 19 所检出源码与 QWeb Reports 为准，部分环境可能走 headless Chromium 等）。模板与 ir.actions.report 写法 见 第十九章；本章只写「装什么、怎么验、常见坑」。

49.1 通用步骤（各系统完成后都要做）

49.1.1 获取源码

git clone https://github.com/odoo/odoo.git --depth 1 --branch 19.0 odoo19
cd odoo19

企业版：将 enterprise 仓库 并列克隆，后续 addons_path 指向其 addons 根。

49.1.2 Python 虚拟环境与依赖

python3 -m venv .venv
source .venv/bin/activate          # Windows CMD: .venv\Scripts\activate.bat
                                   # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -U pip wheel
pip install -r requirements.txt

若 psycopg2 编译失败，优先 安装 OS 级 libpq-dev（Linux） 或 使用已带 wheel 的 Python 版本；Windows 原生 见 49.3。

49.1.3 创建数据库与用户（PostgreSQL）

逻辑：系统用户 postgres 或 sudo -u postgres 下执行 createuser / createdb；应用连接用户 非超级用户 时，需 CREATEDB 或 预先建库。

示例（Linux/macOS，postgres 用户）：

sudo -u postgres createuser -s odoo_dev          # 开发偷懒：超级用户；生产勿用
sudo -u postgres createdb -O odoo_dev odoo_dev   # 可选：空库

生产：单独用户、强密码、无超级用户、按库授权。

49.1.4 最小 odoo.conf（开发）

在 odoo19/ 旁 或 /etc/odoo/ 放配置文件（路径自定）：

[options]
admin_passwd = change-me-master-password
db_host = localhost
db_port = 5432
db_user = odoo_dev
db_password =
addons_path = /path/to/odoo19/addons
data_dir = /path/to/filestore-dev
http_port = 8069
log_level = info

企业版：

addons_path = /path/to/enterprise,/path/to/odoo19/addons,/path/to/custom_addons

49.1.5 首次启动与建库

./odoo-bin -c /path/to/odoo.conf

浏览器打开 http://localhost:8069 → 创建数据库（主密码 即 admin_passwd）→ 勾选 演示数据 按需。

49.1.6 本节练习

1. 简答：为何 必须用 venv 而不是 sudo pip install -r requirements.txt？
2. 判断：admin_passwd 即 数据库里 admin 用户的登录密码。（ ）

参考答案提示：1. 隔离版本、避免搞坏系统 Python。2. 错；admin_passwd 是主控密码（创建/删库等），与登录用户不同。

49.2 Ubuntu 部署流程（22.04 / 24.04 LTS，推荐用于服务器与 WSL）

49.2.1 系统包（编译依赖 + 运行库）

sudo apt update
sudo apt install -y \
  git wget curl \
  build-essential \
  python3-dev python3-venv python3-pip \
  libxml2-dev libxslt1-dev zlib1g-dev \
  libsasl2-dev libldap2-dev libssl-dev \
  libpq-dev libffi-dev libjpeg-dev

可选（报表 PDF）：安装命令与版本、字体、验证 见 §49.6；此处仅保留最小示例：

sudo apt install -y wkhtmltopdf fonts-noto-cjk   # CJK 中文常用；引擎细节见 §49.6

49.2.2 安装 PostgreSQL

sudo apt install -y postgresql postgresql-client
sudo systemctl enable --now postgresql

创建角色与库（开发示例）：

sudo -u postgres createuser -s odoo_dev
sudo -u postgres psql -c "ALTER USER odoo_dev WITH PASSWORD 'your_password';"

odoo.conf 中设置 db_user / db_password。

49.2.3 固定 Python 版本（若系统默认偏旧）

Ubuntu 24.04 常自带 Python 3.12，多数情况 直接 python3 -m venv 即可。若需 deadsnakes 安装 3.11：

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.11 python3.11-venv
python3.11 -m venv .venv

49.2.4 拉代码、venv、依赖

cd ~
git clone https://github.com/odoo/odoo.git --depth 1 --branch 19.0 odoo19
cd odoo19
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip wheel
pip install -r requirements.txt

49.2.5 目录权限与 data_dir

mkdir -p ~/odoo-filestore
chmod 700 ~/odoo-filestore

data_dir 指向该目录；运行 Odoo 的系统用户 须 可写。

49.2.6 前台运行与 systemd（可选）

开发：

./odoo-bin -c ~/odoo.conf --dev=all

--dev=all 仅 可信开发机；生产禁用。

生产示例（systemd 片段，用户 odoo、路径请替换）：

[Unit]
Description=Odoo 19
After=network.target postgresql.service

[Service]
Type=simple
User=odoo
Group=odoo
ExecStart=/home/odoo/odoo19/.venv/bin/python /home/odoo/odoo19/odoo-bin -c /etc/odoo/odoo.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

worker / limit_* 等见 第四十二章。

49.2.7 防火墙（服务器）

sudo ufw allow OpenSSH
sudo ufw allow 8069/tcp    # 仅内网调试；对公网应 **只开 443 经 Nginx**
sudo ufw enable

49.2.8 截图占位

49.2.9 本节练习

1. 实操：在 全新 Ubuntu VM 上跑通 8069 建库。
2. 简答：生产环境 为何 不把 8069 直接暴露公网？

参考答案提示：2. 无 TLS、无速率限制、暴露管理接口；应 Nginx + HTTPS。

49.3 Windows 部署流程（10 / 11）

Windows 上 依赖含 C 扩展（lxml、psycopg2 等），路径最稳的是 WSL2；原生安装 适合 无法启用虚拟化的环境。

49.3.1 方案 A：WSL2 + Ubuntu（强烈推荐）

1. 启用 WSL2：控制面板 → 程序 → 启用或关闭 Windows 功能 → 适用于 Linux 的 Windows 子系统、虚拟机平台；或 wsl --install（以微软文档为准）。
2. 安装 Ubuntu 22.04/24.04（Microsoft Store）。
3. 进入 WSL，完全按 49.2 执行。
4. 访问：Windows 浏览器打开 http://localhost:8069（WSL2 端口自动转发；若异常，用 wsl hostname -I 或 netsh interface portproxy 排查）。

文件放在哪：推荐仓库克隆在 WSL 文件系统（/home/...），勿 把 重度编译 放在 /mnt/c/...（IO 与权限性能差）。

PostgreSQL：二选一——(1) WSL 内 apt install postgresql；(2) Windows 上安装 PostgreSQL EDB，WSL 里 db_host 填 Windows 主机 IP（较折腾，仅特殊需求）。

49.3.2 方案 B：Windows 原生 Python

1. 安装 Python（安装向导勾选 Add to PATH；建议 3.11/3.12 与 Odoo 要求一致）。
2. 安装 PostgreSQL for Windows，记住 端口 5432 与 postgres 用户密码；用 pgAdmin 或 psql 创建 odoo_dev 用户/库。
3. 安装 Git for Windows。
4. 安装 Microsoft C++ Build Tools（「使用 C++ 的桌面开发」工作负载），否则 lxml / gevent 等可能编译失败。
5. PowerShell：

cd $HOME
git clone https://github.com/odoo/odoo.git --depth 1 --branch 19.0 odoo19
cd odoo19
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip wheel
pip install -r requirements.txt

1. wkhtmltopdf：安装 Windows 安装包 并把 bin 加入 PATH（报表用）。
2. 启动：

python odoo-bin -c C:\path\to\odoo.conf

常见坑：终端编码（UTF-8）；长路径；杀毒软件 锁 filestore；企业代理 下 pip 证书。

49.3.3 截图占位

49.3.4 本节练习

1. 简答：WSL2 方案 相对 原生 的 两条优势？
2. 判断：在 /mnt/c/Users/.../odoo19 下编译依赖 一定 比 WSL $HOME 快。（ ）

参考答案提示：2. 错；通常更慢。

49.4 macOS 部署流程（Sonoma / Sequoia，Apple Silicon & Intel）

49.4.1 命令行工具与 Homebrew

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple Silicon：按 brew 提示 将 eval "$(/opt/homebrew/bin/brew shellenv)" 写入 ~/.zprofile。

49.4.2 PostgreSQL

brew install postgresql@16
brew services start postgresql@16
echo 'export PATH="/opt/homebrew/opt/postgresql@16/bin:$PATH"' >> ~/.zshrc   # Apple Silicon 路径按 brew 提示调整
source ~/.zshrc
createuser -s odoo_dev        # 开发示例

49.4.3 Python

优先：Homebrew python@3.12 或 pyenv（多版本切换）。

brew install python@3.12
python3.12 -m venv ~/odoo19/.venv

49.4.4 系统库（减少编译失败）

brew install openssl@3 libpq
export LDFLAGS="-L$(brew --prefix openssl@3)/lib -L$(brew --prefix libpq)/lib"
export CPPFLAGS="-I$(brew --prefix openssl@3)/include -I$(brew --prefix libpq)/include"

再 pip install -r requirements.txt（若仍失败，按报错补库）。

49.4.5 拉代码与启动

cd ~
git clone https://github.com/odoo/odoo.git --depth 1 --branch 19.0 odoo19
cd odoo19
source .venv/bin/activate   # 若 venv 建在 ~/odoo19/.venv
pip install -r requirements.txt
./odoo-bin -c ~/odoo.conf

49.4.6 wkhtmltopdf

Intel：可用 Homebrew 安装 wkhtmltopdf（配方随上游变动，以 brew search 为准）。Apple Silicon：部分构建 非原生，常需 Rosetta 环境 或 与 Odoo 19 实际调用栈一致 的替代方案。完整说明、验证与排障 见 §49.6（并与 第十九章 §19.2 呼应）。

49.4.7 截图占位

49.4.8 本节练习

1. 实操：用 brew services list 确认 PostgreSQL 为 started。
2. 简答：Apple Silicon 上 为何有时要导出 LDFLAGS/CPPFLAGS？

参考答案提示：2. 让 pip 找到 OpenSSL/libpq 头文件与库。

49.5 安装后验证清单（三系统通用）

49.6 报表 PDF / QWeb-PDF 环境（与第十九章 §19.2 衔接）

分工：第十九章 讲 ir.actions.report、QWeb 模板、report_type=qweb-pdf 等 开发面；本节只讲 操作系统与运行时：装什么引擎、字体、如何验收、常见故障。官方报表参考：QWeb Reports。

49.6.1 引擎选型（以所部署的 Odoo 19 为准）

• 历史与常见路径：许多环境仍通过 wkhtmltopdf 将 HTML → PDF。
• 演进：部分版本/配置可能走 headless Chromium 等；以你检出的 odoo 源码、镜像 Dockerfile 与 Source install 为准，勿凭旧博客硬套单一引擎。
• 原则：容器/最小镜像 若缺 引擎二进制 + 字体，易出现 空白 PDF、方块字（tofu）、乱码——与 第十九章 §19.2.1 一致。

49.6.2 Ubuntu / Debian / WSL（与 §49.2 同族）

sudo apt update
sudo apt install -y wkhtmltopdf fonts-noto-cjk
wkhtmltopdf --version

• 发行版自带 wkhtmltopdf 过旧或未打补丁：历史上曾出现 页眉页脚/分页 异常；若报表异常，对照 Odoo 文档 换用 官方推荐的静态包或版本（以 19.0 说明为准）。
• 中文、日文、韩文：除 fonts-noto-cjk 外，可按需增加 fonts-noto-cjk-extra 或业务所需字体；字体必须对运行 Odoo 的系统用户可见（同一台机、同一容器内安装）。

49.6.3 Windows（与 §49.3 衔接）

• 安装 wkhtmltopdf 官方 Windows 包，将 wkhtmltopdf.exe 所在目录 加入 PATH（安装程序常可选）。
• 新终端执行 wkhtmltopdf --version；再在 Odoo 中 打印 任意 QWeb-PDF 报表验收。
• 中文：安装 Noto / 微软雅黑 等 系统级字体（服务进程要能加载到）。

49.6.4 macOS（与 §49.4 衔接）

• Intel：brew install wkhtmltopdf（若配方可用）。
• Apple Silicon：若得到 x86_64 二进制，可能需在 Rosetta 终端或文档指定方式下运行；以本机 wkhtmltopdf --version 与 Odoo 日志中的实际调用为准。若长期不稳定，优先考虑 Linux 服务器 作为 报表生成环境。

49.6.5 容器与自建镜像

• 在镜像构建阶段 安装 PDF 引擎依赖 + CJK 字体，不要只在开发机有字体、生产容器裸奔。
• 验证：进入容器执行 wkhtmltopdf --version（若栈为 wkhtml）；再跑一条 含中文的 HTML → PDF 试转。

49.6.6 验收与排障摘要

命令行快速检查（与 第十九章 §19.2.2 一致）：

wkhtmltopdf --version
# 同时查看 Odoo 日志中实际调用的命令或报错栈

49.6.7 本节练习

1. 简答：PDF 中文乱码常见 三种原因？（可与 第十九章 §19.2.4 对照。）
2. 实操：在目标环境执行 wkhtmltopdf --version，并在界面 打印 一份含中文的 QWeb-PDF。

参考答案提示：1. 缺字体、子集/嵌入问题、引擎不支持该字体格式。2. 见上表 验收。

49.7 常见问题速查

本章综合练习

1. 对比表：Ubuntu / WSL / Windows 原生 / macOS 各写 一条 最费时的步骤 及 原因。
2. 综合：生产上线 时，在本章基础上 必须再读 第四十二章 的 哪三节标题（自拟或抄目录）？
3. 实操：在 任一系统 写出 从克隆到 odoo-bin 首次监听 8069 的 命令序列（10 行以内，路径用变量占位）。

本章与 第四十二章 安装与配置、第四十三章 CI/CD、第十九章 §19.2（PDF 理论） 衔接；QWeb-PDF 系统依赖 见 §49.6。官方源码安装见 Source install。