Odoo 20 常用命令与运维实战
Odoo 20 服务端 odoo-bin 命令行实测全解：16 个子命令矩阵、模块管理 -i/-u 与 module 子命令族（参数顺序/8069 冲突排障实录）、scaffold 脚手架与 deploy 远程部署、db 子命令族与 pg_dump 备份恢复、Web 数据库管理器备份/复制含 neutralize 脱敏、shell 交互式 ORM 控制台。
Odoo 20 常用命令与运维实战
目标：把 Odoo 20 社区版服务端
odoo-bin命令行体系一次讲清——16 个子命令总览、模块管理（-i/-u与module子命令族）、脚手架与远程部署（scaffold/cloc/deploy）、数据库全生命周期 CLI（db子命令族 +pg_dump直连 + Web 数据库管理器备份/复制）、shell交互与neutralize数据脱敏。全部命令与回显来自 2026-10-27 在 Ubuntu 22.04 上的真实实测；配置文件逐项语义见 《Odoo 20 配置参数详解》，部署过程见 《Odoo 20 Docker Compose 部署实战》。
一、环境信息
- 操作系统：Ubuntu 22.04（x86_64，真实服务器视角）
- Odoo：社区版 Odoo Server 20.0-20261015（
odoo --version实测回显） - 数据库：PostgreSQL 17（服务端
db主机名可达，端口 5432） - 命令入口：
odoo（deb 包安装提供的/usr/bin/odoo，指向odoo-bin） - 实测账号：PostgreSQL 角色
odoo/odoo20pg；Odoo 应用管理员admin/q1w2e3r4（演示口令）；数据库管理器主控口令q1w2e3r4 - 实测数据库：
odoo20main（空库）、odoo20demo（演示库，已装 CRM/库存与自定义模块） - 自定义模块：
x_odoo_tools（本文用scaffold现场生成，贯穿全部模块管理命令演示）
二、工具概览
Odoo 服务端 CLI 的顶层入口只输出子命令清单（服务端参数在 server 子命令下，详见配置篇 3.1 节）：
odoo --help
实测回显（完整）：
Usage: odoo [options]
Odoo Server version 20.0-20261015
Options:
--version show program's version number and exit
-h, --help show this help message and exit
Common options:
-c PATH, --config=PATH
specify alternate config file
--save save configuration to ~/.odoorc (or to
~/.openerp_serverrc if it exists)
-i MODULE,..., --init=MODULE,...
install one or more modules (comma-separated list, use
"all" for all modules), requires -d
-u MODULE,..., --update=MODULE,...
update one or more modules (comma-separated list, use
"all" for all modules), requires -d
--dev MODE,MODE,MODE,MODE,MODE,MODE,MODE,MODE
MODE: any of all,pug,xml,qweb,template,reset,strings,t
est - pug: enable Pug template engine; xml: read
template qweb from xml file; template: read template
qweb from file; reset: force template re-render and
store, can be combined with `xml` and `template`.
strings: disable updating template translations;
test: enable a test mode for template rendering
--filter-time=FILTER_TIME
Filter logging by time
--filter-module=FILTER_MODULE
Filter logging by module name
--filter-function=FILTER_FUNCTION
Filter logging by function name
...
顶层帮助还包含数据库连接、HTTP、多进程、日志等全部服务端选项（与配置篇参数表一一对应）。子命令矩阵（Odoo 20 实测共 16 个）：
| 子命令 | 作用 | 本文实测 |
|---|---|---|
server（默认） | 运行服务端 | 部署篇实测 |
shell | 带完整 ORM 环境的交互式 Python | 7.1 节 |
db | 数据库管理器 CLI（init/dump/load/duplicate/rename/drop） | 6.1 节 |
module | 模块管理 CLI（install/upgrade/uninstall/force-demo/list） | 第四章 |
scaffold | 生成模块骨架 | 5.1 节 |
cloc | 模块代码行数统计 | 5.2 节 |
deploy | HTTP 方式向运行中的实例部署模块 | 5.3 节 |
neutralize | 数据库脱敏（消除生产数据副作用） | 7.2 节 |
i18n | 导入/导出翻译文件（po/pot 协作流） | 未展开（低频，见八节注意事项） |
upgrade_code | 核心代码迁移工具（Odoo 开发者用） | 8 节简述 |
populate | 测试数据填充 | — |
duplicate | 数据库复制（独立顶层入口） | — |
wsgi | WSGI 服务器启动 | — |
console | 无 ORM 的纯 Python 控制台 | — |
start | 兼容旧版的启动别名 | — |
服务器上确认入口位置与实际指向：
which odoo && head -1 "$(which odoo)"
实测回显：
/usr/bin/odoo
#!/usr/bin/python3
三、前置条件
- 服务器上已有一套可运行的 Odoo 20 且数据库可达（部署见本专栏部署篇；同机包管理器部署的
db_host默认走本机 socket，跨机部署需在配置文件指定 PostgreSQL 地址——见配置篇 5.1 节）。 - CLI 管理命令与运行中的服务共享 8069 端口，端口型命令（
server、deploy目标端） 要么停服务要么换端口；非端口型命令（db/module/scaffold/shell --no-http等）可直接在服务运行时执行。本文所有 CLI 实测均在服务运行中完成。 db子命令族要求配置文件中的数据库连接凭据可用（db_user/db_password），或命令行显式给出--db-user/--db-password。- 命令执行用户对
data_dir（默认/var/lib/odoo）有读写权限（deb 安装即odoo用户）。
四、模块管理命令详解
Odoo 模块管理有两条路径：server 形态的 -i/-u 参数（「装完即停」配合 --stop-after-init，脚本化首选）与 module 子命令族（语义化动词，交互排查友好）。两者底层同源，都走 ORM 注册表重载。
4.1 module list —— 已安装模块清单
odoo module list -d odoo20demo
实测回显（节选，实测首尾）：
Modules in database 'odoo20demo':
base 20.0.1.3 20.0.1.3 'base' base
web 20.0.1.4 20.0.1.4 'web' base
base_setup 20.0.1.1 20.0.1.1 'base_setup' base
...
crm 20.0.1.2 20.0.1.2 'CRM' sales
...
x_odoo_tools 20.0.0.1 20.0.0.1 'X Odoo Tools' tools
57 modules loaded.
输出为五列：模块名 / 安装版本 / 最新版本 / 显示名 / 分类；末行 57 modules loaded. 是该库已安装模块总数。已安装模块间依此核对版本差（安装版本 < 最新版本说明有待升级）。
⚠️ 排障实录（参数顺序坑）：子命令形态下
-d等 server 参数必须写在子命令之后。写成odoo -d odoo20demo module list（server 形态的直觉顺序）实测报错：usage: odoo [-h] [--version] [-c PATH | --save] [-i MODULE,...] ... odoo: error: unrecognized parameters: 'list'记忆规则：出现动词（
list/install/...）即子命令模式，server 参数全部跟在动词后面。
4.2 -i / -u —— server 形态安装与更新
odoo -d odoo20demo -i x_odoo_tools --stop-after-init --no-http
实测回显（关键行）：
2026-10-27 15:44:52,311 259 INFO odoo20demo odoo.modules.registry: module x_odoo_tools: creating or updating database tables
2026-10-27 15:40:37,475 236 INFO odoo20demo odoo.modules.loading: Modules loaded in 2.34s, 57 modules loaded
--stop-after-init 完成装载即退出（脚手架模块版本号在 ir_module_module 中被规范化为 20.0.0.1——模块清单版本 0.1 前自动补版本大段，见 5.1 节 manifest 实测）。-u 更新同形态：
odoo -d odoo20demo -u x_odoo_tools --stop-after-init --no-http
实测回显（关键行）：
2026-10-27 15:43:30,673 246 INFO odoo20demo odoo.modules.registry: module x_odoo_tools: creating or updating database tables
-i/-u 支持逗号分隔多模块与 all（-u all 全库更新，大版本升级场景常用）。
⚠️ 排障实录（端口冲突）：不带
--no-http执行时，CLI 进程会尝试绑定 8069，与运行中的服务冲突：2026-10-27 15:42:10,123 243 ERROR ? odoo.service.server: Couldn't bind on port 8069. No server will be available. Exiting. 2026-10-27 15:42:10,124 243 ERROR ? odoo: Failed to start server, port 8069 already in use.根因：deb 安装的服务以 systemd 托管占用 8069，
docker exec/终端里直接跑odoo -d ... -i ...是第二个进程。规避：管理命令一律加--no-http（模块装载不需要 HTTP）；确需 HTTP 的场景先sudo systemctl stop odoo。
4.3 module install / upgrade / uninstall
子命令族动词化形态（服务运行中可直接执行）：
odoo module install -d odoo20demo x_odoo_tools
实测回显（尾部）：
2026-10-27 15:45:23,475 292 INFO odoo20demo odoo.registry: Registry loaded in 0.090s
2026-10-27 15:45:23,475 292 INFO odoo20demo odoo.addons.base.models.ir_module: getting next ir.actions.todo()
x_odoo_tools 20.0.0.1 20.0.0.1 'installed' x_odoo_tools
末行是安装后状态自检：模块名 安装版本 最新版本 'installed' 分类。更新与卸载：
odoo module upgrade -d odoo20demo x_odoo_tools
odoo module uninstall -d odoo20demo x_odoo_tools
uninstall 实测回显（关键行）：
2026-10-27 15:45:42,642 310 INFO odoo20demo odoo.addons.base.models.ir_module: ALLOW access to module.module_uninstall on ['x_odoo_tools'] to user __system__ #1 via n/a
2026-10-27 15:45:42,652 310 INFO odoo20demo odoo.modules.loading: Reloading registry once more after uninstalling modules
卸载后 module list 中该模块不再出现（list 只列已安装模块）。注意 uninstall 走的是 __system__ 用户（超级用户）授权链，业务数据表会随卸载清理——生产库卸载模块前先备份（第六章）。
4.4 module force-demo
给指定库补装全部演示数据（等价建库时勾选 Demo Data）：
odoo module force-demo -d odoo20main
适用：先建了空库、后需要演示数据的环境。已含演示数据的库重复执行无副作用（幂等跳过）。
五、脚手架与模块部署
5.1 scaffold —— 模块骨架生成
odoo scaffold x_odoo_tools /mnt/extra-addons
实测生成清单（find 回显）：
/mnt/extra-addons/x_odoo_tools
/mnt/extra-addons/x_odoo_tools/__init__.py
/mnt/extra-addons/x_odoo_tools/__manifest__.py
/mnt/extra-addons/x_odoo_tools/controllers/__init__.py
/mnt/extra-addons/x_odoo_tools/controllers/controllers.py
/mnt/extra-addons/x_odoo_tools/demo/demo.xml
/mnt/extra-addons/x_odoo_tools/i18n/zh_CN.po
/mnt/extra-addons/x_odoo_tools/models/__init__.py
/mnt/extra-addons/x_odoo_tools/models/models.py
/mnt/extra-addons/x_odoo_tools/security/ir.model.access.csv
/mnt/extra-addons/x_odoo_tools/static/description/icon.png
/mnt/extra-addons/x_odoo_tools/static/src/js/tour.js
/mnt/extra-addons/x_odoo_tools/views/templates.xml
/mnt/extra-addons/x_odoo_tools/views/views.xml
骨架即最小可安装模块，manifest 默认内容：
{
'name': 'X Odoo Tools',
'version': '0.1',
'category': 'Tools',
'summary': 'Short (1 phrase) summary of the module\'s purpose',
'author': 'Your Company',
'website': 'https://www.yourcompany.com',
'license': 'LGPL-3',
'depends': ['base'],
'data': [
# 'security/ir.model.access.csv',
'views/views.xml',
'views/templates.xml',
],
'demo': [
'demo/demo.xml',
],
}
要点：depends 起步只依赖 base；security/ir.model.access.csv 默认注释，模型加了权限行再放开；新目录加入后需在配置文件 addons_path 中包含 /mnt/extra-addons 并重启服务（配置篇 5.4 节）。
5.2 cloc —— 代码量统计
odoo cloc -p /mnt/extra-addons/x_odoo_tools
实测回显（真实）：
Date 2026-10-27 15:34
Extra dir -
File Files Lines Code Documentation
XML 2 43 37 0
Python 3 33 27 2
JSON 1 1 0 0
Total (1) 6 77 64 2
Odoo Files Lines Code Documentation
Python 32 3892 3029 435
Total (2) 32 3892 3029 435
上半段是目标模块自身代码量，下半段 Odoo 段是其依赖链上官方模块的代码量（售后与审计场景评估自定义代码占比用）。
5.3 deploy —— 向运行实例远程部署
deploy 走 HTTP 把本地模块 zip 上传到正在运行的实例并安装（等价网页端「应用 → 导入模块」）：
odoo deploy --db odoo20main --login admin --password q1w2e3r4 /mnt/extra-addons/x_odoo_tools http://localhost:8069
实测回显（真实）：
Zipping module directory x_odoo_tools...
Uploading module file...
部署后在目标库核对：
odoo module list -d odoo20main | grep x_odoo_tools
实测回显：
x_odoo_tools 20.0.0.1 20.0.0.1 'installed' x_odoo_tools
适用：CI/CD 流水线模块交付（账号用 API 访问专用用户，演示为管理员）；目标 URL 填实例对外地址，跨机部署把 http://localhost:8069 换成实例地址即可。
六、数据库管理命令详解
Odoo 数据库运维三条路径：db 子命令族（服务端本机 CLI）、pg_dump（PostgreSQL 原生）、Web 数据库管理器（远程可用）。三者都产生 filestore-aware 的备份——Odoo 附件二进制存于 data_dir/filestore/<库名>/（配置篇 5.4 节），纯 SQL dump 不含附件。
6.1 db 子命令族
六个动作全部实测（动作参数为位置参数，注意与选项参数的区别）：
odoo db dump odoo20demo /tmp/odoo20demo-cli.zip
实测回显（尾部）：
2026-10-27 15:47:22,313 292 INFO odoo20demo odoo.addons.base.models.ir_module: Dump database odoo20demo to /tmp/odoo20demo-cli.zip
Backup database odoo20demo to /tmp/odoo20demo-cli.zip
ls -la /tmp/odoo20demo-cli.zip
实测回显：
-rw-r--r-- 1 odoo odoo 4006610 Oct 27 15:47 /tmp/odoo20demo-cli.zip
zip 内含 dump.sql 与 filestore/ 目录。恢复用 load（目标库自动创建，无需先建）：
odoo db load odoo20clirestore /tmp/odoo20demo-cli.zip
实测回显（尾部）：
Restore database odoo20clirestore from /tmp/odoo20demo-cli.zip
复制、改名、删除：
odoo db duplicate odoo20main odoo20clidup
odoo db rename odoo20clidup odoo20clidup2
odoo db drop odoo20clidup2
duplicate 实测回显：
Copy database odoo20main to odoo20clidup
三步链执行后 PostgreSQL 侧核对：
psql -U odoo -d postgres -Atc "SELECT datname FROM pg_database WHERE datname LIKE 'odoo20cli%'"
实测回显（rename 后 drop 前）：
odoo20clidup2
drop 后该查询无结果行（CLI 正常退出码 0）。另附建库动作 db init（odoo db init <库名> 建空业务库，与 Web 管理器建库等价）。dump/load 也支持 --format 选择 SQL/zip 形态，dump 加 -f/--force 覆盖已存在文件。
6.2 pg_dump 直连备份
Odoo db 命令本质是对 pg_dump/pg_restore 的封装；绕过 Odoo 直接用 PostgreSQL 工具备份 SQL 层：
pg_dump --version
PGPASSWORD=odoo20pg pg_dump -h db -U odoo -d odoo20demo -Fc -f /tmp/odoo20demo-pg.dump
ls -la /tmp/odoo20demo-pg.dump
实测回显：
pg_dump (PostgreSQL) 18.6
-rw-r--r-- 1 odoo odoo 3998666 Oct 27 15:48 /tmp/odoo20demo-pg.dump
两个实测发现：其一，客户端工具版本（18.6）高于服务端（17）为 PostgreSQL 官方支持的向后兼容形态，dump 正常；其二，-Fc 定制格式体积与 Odoo zip 备份接近（差值即 filestore 部分），恢复用 pg_restore -C 或先 createdb 再导入。选型建议：带附件的业务库用 Odoo zip 备份（一步含 filestore）；仅 SQL 结构与数据的迁移、跨版本导入用 pg_dump；两者都做则最稳。
6.3 Web 数据库管理器备份与复制
浏览器访问 http://<服务器>:8069/web/database/manager（主控口令即配置文件 admin_passwd）：
- Backup：选库 → 格式 zip（含 filestore，推荐）→ 下载。等价 CLI
db dump。 - Restore：填新库名 → 上传 zip。等价 CLI
db load。完整实测回显与注意事项见 《Odoo 20 Docker Compose 部署实战》备份恢复章节。 - Duplicate：填源库与目标库名，可选勾选 Neutralize——勾选后复制的同时执行全部模块的
neutralize.sql（官方文档原文：复制生产库为「脱敏测试库」的标准做法，"Typically, you want to duplicate your production database into a neutralized testing database. It can be done by checking the neutralize box when prompted"）。
duplicate 实测（表单方式调用，勾选 neutralize）：
curl -s -X POST http://127.0.0.1:8069/web/database/duplicate \
-d 'master_pwd=q1w2e3r4&name=odoo20demo&new_name=odoo20webdup&neutralize_database=true' \
-o /dev/null -w 'HTTP %{http_code}\n'
实测回显：
HTTP 303
PostgreSQL 侧核对：
odoo20webdup
库列表出现 odoo20webdup，复制成功。生产节奏建议：生产 → 测试库一律走 duplicate + Neutralize，避免测试环境向真实客户发邮件等副作用（脱敏原理见 7.2 节）。
七、shell 与数据库脱敏
7.1 odoo shell —— 交互式 ORM 控制台
odoo shell -d odoo20demo --no-http
实测交互（标准输入喂入两条查询）：
>>> print('USERS:', env['res.users'].search_count([]))
USERS: 4
shell 启动时载入目标库完整注册表，env 即 ORM 环境对象（等价模型方法里的 self.env），可直接执行任意 ORM 操作——数据修复、批量更新、模型探测的一线工具。常用形态：
>>> env['ir.module.module'].search_count([('state','=','installed')])
57
>>> env['res.partner'].search([], limit=3).mapped('name')
退出 exit()；只读排查可配合 --no-http（不占端口）。
7.2 neutralize —— 数据库脱敏
odoo neutralize -d odoo20demo --stop-after-init --no-http
实测回显（关键行）：
Starting neutralization for database odoo20demo...
Neutralization finished for database odoo20demo
机制：遍历该库全部已安装模块，逐个执行模块内置的 neutralize.sql——重置用户口令、清空邮件服务器凭据、停用定时邮件任务、清除支付/银行敏感配置等，使业务数据可安全用于测试。适用三场景：duplicate 管理器勾选项的 CLI 等价物、把生产备份导入测试环境后的例行步骤、演示环境数据准备。注意：neutralize 后管理员口令被重置为默认值，首次登录需按 Odoo 提示重设。
八、注意事项
- 命令形态二分：出现动词即子命令模式（server 参数跟在动词后）；纯参数模式（
odoo -d ... -i ...）走 server 默认子命令。混用会报unrecognized parameters（4.1 节排障实录）。 --stop-after-init+--no-http是脚本化铁律：前者防止命令挂起常驻，后者避开 8069 冲突（4.2 节排障实录）。- 破坏性三思：
db drop/module uninstall不可逆；执行前先db dump（第六章）。 - zip 备份与 filestore：
db dumpzip 已含 filestore；自建pg_dump方案要自行同步data_dir/filestore/<库名>/，否则附件丢失。 - 部署篇的容器形态差异：容器内执行 CLI 用
docker exec <容器名> odoo ...，且容器镜像的环境变量（HOST/USER/PASSWORD等）会转译为命令行参数——容器侧行为见 《Odoo 20 Docker Compose 部署实战》，本文按裸机/包管理器服务器形态叙述。 upgrade_code子命令（源码迁移工具，含--dry-run）面向 Odoo 框架开发者做核心代码跨版本改写，运维场景不涉及，本文未实测展开。- 翻译文件操作走
odoo i18n import/export（导出 po/pot 供翻译协作），日常运维低频，本文未展开实测。
九、常见问题
Q1：odoo: error: unrecognized parameters: 'xxx'？
参数顺序错——子命令模式下 server 参数要跟在动词之后（odoo module list -d 库名，不是 odoo -d 库名 module list），见 4.1 节。
Q2：CLI 装模块报 Couldn't bind on port 8069？
与运行中的服务端口冲突。加 --no-http（推荐）或先停服务（sudo systemctl stop odoo），见 4.2 节。
Q3：-i 装不上自定义模块、日志报 invalid addons directory？
模块目录未纳入 addons_path，或目录内缺 __manifest__.py。核对配置篇 5.4 节的启动日志两行告警定位。
Q4：db load 恢复报目标库已存在？
load 不覆盖既有库。先 db drop 旧库或换新库名；同库轮换场景可 dump → drop → load 三步走。
Q5：备份 zip 很小、恢复后附件丢失？
确认用的是 db dump 的 zip 格式（含 filestore）而非纯 SQL；若历史备份只有 SQL，附件需从 data_dir/filestore/<库名>/ 单独找回并按目录放置。
Q6：deploy 上传报权限或登录失败？
deploy 需要目标实例的可登录账号且该账号有「应用」导入权限（管理员或有应用管理权限的用户）；演示账号 admin/q1w2e3r4 仅限测试环境。
Q7：多库服务器上 CLI 命令操作了哪个库？
一切以 -d 指定为准（CLI 不走 dbfilter——那是 Web 请求的路由器，见配置篇 5.3 节）；不传 -d 的命令只做与库无关的操作（如 scaffold、cloc）。
Q8：shell 里修改数据没生效？
shell 每条语句独立，ORM 写操作后要 env.cr.commit() 提交事务再退出；只读查询无需提交。
十、参考链接
- 官方命令行参考（CLI 全子命令）：https://www.odoo.com/documentation/20.0/developer/reference/cli.html
- 官方部署指南（服务化与参数体系）：https://www.odoo.com/documentation/20.0/administration/deploy.html
- 官方 on-premise 管理文档（数据库复制与 neutralize）：https://www.odoo.com/documentation/20.0/administration/on_premise.html
- 服务端源码（odoo-bin 入口与子命令实现）：https://github.com/odoo/odoo/tree/20.0/odoo/cli
- 本专栏配置详解（参数语义与排障对照）：《Odoo 20 配置参数详解》
- 本专栏部署实测（容器形态与备份恢复回显）：《Odoo 20 Docker Compose 部署实战》
- 本专栏选型认知：《Odoo 介绍与选型指南》