把 Odoo 从 17.0 升到 18.0，重启后某个自定义模块整页报错、菜单直接灰掉——这是升级里最典型的「模块不兼容」。本篇讲清三件事：报错到底从哪来、生产环境怎么最快回退、以及修好之后如何正向升级，而不是每次都 rollback 了事。
升级后模块为什么突然不兼容
Odoo 每个大版本都会动 ORM API、字段属性、视图写法和权限模型。自定义模块或第三方模块只要用到被改掉的接口，升级后第一次 -u 就会炸。常见触发点就四类：manifest 版本前缀没改、依赖版本被钉死、Python 导入了已删除的 API、XML 视图引用了被移除的字段。先别急着回退，得先看清是哪一种。
第一步：从日志拿真实报错，别信界面弹窗
后台那个红框只告诉你「出错了」，真正原因在日志里。先 tail 出最近 100 行，顺着 Traceback 最底下那行找模块名和报错类型：
sudo tail -n 100 /var/log/odoo/odoo.log
# 若用 systemd 托管
journalctl -u odoo -n 100 --no-pager第二步：三类根因快速定位
踩坑实录
上周帮客户从 17.0 升 18.0，重启后销售模块整个灰掉。我第一反应是 -u sale_custom 强制升级，结果日志刷出 ValueError: Field 'commission_rate' does not exist——新版本把那个 Float 改成了 Many2one，老数据还躺在旧列里。我原以为 -u 会自动迁，其实 manifest 的 version 还写着 17.0.1.0.0，Odoo 压根没跑迁移脚本。最后用升级前 2 小时的 pg_dump 把库还原，再把 manifest 改成 18.0.1.0.0 并补 migrations/18.0.1.0.0/post-migrate.py 才过上。
第三步：生产环境怎么回退最快
git checkout 回上一个 addons 标签，重启 Odoo，库结构没动，站点立刻恢复。# 还原升级前备份（最稳）
sudo -u postgres pg_dump odoo > /tmp/pre_upgrade.dump # 升级前已做
psql -c "ALTER DATABASE odoo RENAME TO odoo_broken;"
psql -c "CREATE DATABASE odoo TEMPLATE template0;"
psql odoo < /tmp/pre_upgrade.dump
# 临时禁用坏模块止血
psql odoo -c "UPDATE ir_module_module SET state='uninstalled' WHERE name='sale_custom';"注意：直接 UPDATE state 有丢数据风险，只作应急止血，根上还是要还原备份。
第四步：修好再正向升级
别永远 rollback。对齐 manifest 版本前缀，在模块里加 migrations/ 目录写 pre/post-migrate.py 处理字段改名和数据搬迁，先在 staging 库试跑：
./odoo-bin -u sale_custom -d staging_db --stop-after-init没有报错再上生产。每个 Odoo 大版本维护一条独立分支，别在一个分支里跨版本混写。
升级前必做三件事（速查表）
常见问题
Odoo 升级一定要停服吗？
建议停。升级会改数据库结构，运行中写入会导致结构不一致，最好放在维护窗口内操作。
manifest 版本号到底填什么？
前两段必须等于服务器大版本，例如 18.0 服务器就填 18.0.x.y.z。Odoo 靠这个判断是否要跑迁移脚本，填错就不跑。
回退后模块还能用吗？
只要从升级前备份还原，模块和老数据都完好；之后按本文第四步正向修好即可。
你在 Odoo 升级时还踩过哪些模块的坑？欢迎在 fenij.com 留言，一起把这份排障清单补全。
