Docker部署Odoo15无法识别addons目录下OCA第三方自定义模块

按以下顺序逐一排查，覆盖绝大多数异常场景： #

1. 修复addons目录权限 #

官方odoo:15.0镜像内运行服务的用户UID/GID均为1001，宿主机挂载目录权限不匹配时，odoo进程无读取权限，会直接跳过该目录下的所有模块。
在docker-compose.yml所在目录执行以下命令修正权限：

sudo chown -R 1001:1001 ./addons
sudo chmod -R 755 ./addons

注意：不要为了省事给目录设777权限，odoo内置安全规则会直接拒绝读取全局可写目录下的模块，反而导致加载失败。

2. 检查模块目录层级 #

Odoo扫描模块的规则是：addons路径下的一级子文件夹为独立模块，模块文件夹根目录必须直接存在__manifest__.py文件。
最常见的错误是把整个OCA仓库文件夹直接丢进addons目录，多嵌套了一层目录导致扫描不到：
❌ 错误结构示例：

./addons/
└── oca-server-tools/  # 整个仓库文件夹，不是可识别的模块
    └── module_auto_update/  # 这层才是真正的独立模块
        └── __manifest__.py

✅ 正确结构示例：

./addons/
└── module_auto_update/  # 模块文件夹直接放在addons一级目录
    └── __manifest__.py  # manifest文件直接存放在模块根目录

如果不想拆分OCA仓库的目录结构，可以在compose配置里把每个OCA仓库的路径单独作为volume挂载到/mnt下的独立路径，再统一写到addons-path参数里即可。

3. 强制指定addons加载路径 #

如果默认镜像的addons路径配置被.env内的参数覆盖，会导致系统不扫描/mnt/extra-addons目录。修改docker-compose.yml中odoo服务段，新增command参数强制指定加载路径：

services:
  odoo:
    image: odoo:15.0
    env_file: .env
    depends_on:
      - postgres
    ports:
      - "127.0.0.1:8069:8069"
    volumes:
      - data:/var/lib/odoo
      - ./addons:/mnt/extra-addons
    # 新增以下配置
    command: >
      odoo
      --addons-path=/usr/lib/python3/dist-packages/odoo/addons,/mnt/extra-addons

注意：必须把odoo自带模块的路径/usr/lib/python3/dist-packages/odoo/addons加到路径列表里，否则系统自带模块也会加载失败。

4. 按正确顺序重启并刷新模块列表 #

改完所有配置后严格按以下步骤操作：

• 执行docker-compose down停止现有容器
• 执行docker-compose up -d重新启动，等待30秒待odoo服务完成初始化
• 登录Odoo后台进入「应用」菜单，先移除搜索栏默认开启的「官方应用商店」过滤器（默认只显示线上应用商店的模块，会过滤掉本地自定义模块）
• 点击左上角「更新应用列表」按钮，确认后等待刷新完成，即可在列表中看到上传的第三方模块。

兜底排查方法 #

如果以上操作完成后仍看不到模块，进入容器内部验证加载状态：

1. 执行docker-compose exec odoo bash进入odoo容器命令行
2. 执行ls /mnt/extra-addons，如果看不到你上传的模块文件夹，说明volume挂载异常，检查宿主机./addons目录是否和docker-compose.yml处于同级目录
3. 执行odoo --list-modules，查看输出的模块列表中是否包含你上传的第三方模块，如果命令行输出里存在对应模块，后台看不到就是过滤器未移除的问题。

内容的提问来源于stack exchange，提问作者jakarina