Doodba

![]([***]

Doodba 代表 Docker Odoo Base（Docker Odoo 基础镜像），是一个高度定制化的镜像，用于将 Odoo 部署其中，但本身不包含 Odoo。

概述

是的，此镜像的目的是作为构建您自己 Odoo 项目的基础，因为大多数 Odoo 项目最终都需要大量自定义补丁、合并代码、仓库等。通过此镜像，您可以获得一系列最佳实践和工具，使团队拥有标准化的 Odoo 项目结构。

顺便说一句，我们使用 Debian。希望您喜欢。

为什么需要 Doodba？

因为开发 Odoo 很困难。您需要大量自定义、依赖项，而且如果要从一个版本迁移到另一个版本，过程会很痛苦。

此外，没有人希望直接使用上游的 Odoo，您很可能至少需要添加自定义补丁和插件，因此我们需要一种方法将所有内容整合在一起，并能快速在任何地方运行。

如何使用？

您可以通过我们的 [脚手架][] 立即开始使用。

镜像使用方法

基本上，您需要关注的所有目录都位于 /opt/odoo 下。其结构如下：

custom/
    entrypoint.d/
    build.d/
    conf.d/
    ssh/
        config
        known_hosts
        id_rsa
        id_rsa.pub
    dependencies/
        apt_build.txt
        apt.txt
        gem.txt
        npm.txt
        pip.txt
    src/
        private/
        odoo/
        addons.yaml
        repos.yaml
common/
    entrypoint.sh
    build.sh
    entrypoint.d/
    build.d/
    conf.d/
auto
    addons/
    odoo.conf

下面逐一说明。

/opt/odoo/custom：核心目录

这里存放与您项目相关的所有内容。

/opt/odoo/custom/entrypoint.d

容器启动时，在执行您指定的命令之前，会运行此目录下的所有可执行文件。

/opt/odoo/custom/build.d

此目录下的可执行文件将与 /opt/odoo/common/build.d 中的文件合并。

合并后的可执行文件将按字母顺序（升序）排序并依次运行。

/opt/odoo/custom/conf.d

此目录下的文件会在入口点处理时进行环境变量替换，并合并到 /opt/odoo/auto/odoo.conf 中。

/opt/odoo/custom/ssh

其结构必须与标准 ~/.ssh 目录相同，包括 config、known_hosts 文件。实际上，它完全等同于 ~root/.ssh。

config 文件可以包含 IdentityFile 键，用于指定访问主机时使用的私钥。除非另有指定，否则默认使用此目录下的 identity[.pub]、id_rsa[.pub] 或 id_dsa[.pub] 文件。

这对于使用部署密钥授予对私有仓库的 git 访问权限非常有用。

示例：若 ssh 文件夹中有一个名为 my_private_key 的私钥文件，用于访问主机 repo.example.com，则 config 文件中应包含类似以下内容：

Host repo.example.com
  IdentityFile ~/.ssh/my_private_key

或者，您也可以直接将密钥放在 id_rsa 和 id_rsa.pub 文件中，无需添加 config 文件即可默认工作。

默认启用主机密钥检查，这意味着您需要为任何通过 SSH 访问的仓库提供 known_hosts 文件。

若要为某个仓库禁用主机密钥检查，配置如下：

Host repo.example.com
  StrictHostKeyChecking no

有关此目录的更多信息，请查看 [Digital Ocean 文章][ssh-conf]。

/opt/odoo/custom/src

这里存放项目的实际源代码。

存放代码时，您可以：

• 使用 [repos.yaml][]，在构建时自动填充内容。
• 直接复制所有代码到此处。

建议：除 [private][] 外，所有内容都使用 [repos.yaml][]，并在 .gitignore 和 .dockerignore 文件中忽略此目录下除 [private][] 之外的所有文件夹，规则如下：

odoo/custom/src/*
!odoo/custom/src/private
!odoo/custom/src/*.*

/opt/odoo/custom/src/odoo

【必需】您的 Odoo 项目源代码。

您可以选择 Odoo 版本，甚至使用 [repos.yaml][] 合并多个 PR。您可能考虑的版本包括：

• [Original Odoo][]（Odoo ***版本），由 [Odoo S.A.] 开发。

• [OCB][]（Odoo Community Backports，Odoo 社区回溯版），由 [OCA] 开发。在***版本基础上增加了一些功能，但降低了部分稳定性要求。

• [OpenUpgrade][]，由 [OCA] 开发。***版本在新版本发布时的冻结版本，包含迁移脚本。

/opt/odoo/custom/src/private

【必需】项目的私有插件文件夹。

/opt/odoo/custom/src/repos.yaml

git-aggregator 配置文件。

示例如下：

yaml
# Odoo 必须位于 `odoo` 文件夹中，Doodba 才能正常工作
odoo:
  defaults:
    # 使用 git 浅克隆，速度更快。
    # 测试和生产环境中 $DEPTH_DEFAULT 为 1，开发环境中为 100。
    # $DEPTH_MERGE 始终为 100。
    # 您也可以使用任何整数值。
    depth: $DEPTH_MERGE
  remotes:
    origin: [***]
    odoo: [***]
    openupgrade: [***]
  # $ODOO_VERSION 即 Odoo 版本，如 "11.0"
  target: origin $ODOO_VERSION
  merges:
    - origin $ODOO_VERSION
    - odoo refs/pull/25594/head # 从 search_filters.js 暴露 `Field`

web:
  defaults:
    depth: $DEPTH_MERGE
  remotes:
    origin: [***]
    tecnativa: [***]
  target: origin $ODOO_VERSION
  merges:
    - origin $ODOO_VERSION
    - origin refs/pull/1007/head # web_responsive 搜索功能
    - tecnativa 11.0-some_addon-custom # 仅客户专用分支

仓库自动下载

即使 repos.yaml 中缺少某些仓库，Doodba 也能自动下载 git 仓库。如果在 [addons.yaml][] 中使用了某个仓库（特殊的 [private][] 仓库除外），Doodba 会自动下载。这有助于保持部署定义的简洁（DRY）。

您可以通过以下环境变量配置此行为（显示默认值）：

• DEFAULT_REPO_PATTERN="[***]{}.git"
• DEFAULT_REPO_PATTERN_ODOO="[***]"

如您所料，我们使用类似 str.format(repo_basename) 的方式基于这些变量计算默认远程源。例如，若要使用您自己的仓库作为默认远程源，只需在 docker-compose.yaml 中添加以下构建参数：

yaml
# [...]
services:
  odoo:
    build:
      args:
        DEFAULT_REPO_PATTERN: &origin "[***]{}.git"
        DEFAULT_REPO_PATTERN_ODOO: *origin
# [...]

例如，若 repos.yaml 文件为空，而 addons.yaml 包含以下内容：

yaml
server-tools:
- module_auto_update

则会生成并使用 /opt/odoo/auto/repos.yaml 文件来下载 git 代码：

yaml
/opt/odoo/custom/src/odoo:
  depth: $DEPTH_DEFAULT
  remotes:
    origin: [***]
  target: origin $ODOO_VERSION
  merges:
    - origin $ODOO_VERSION
/opt/odoo/custom/src/server-tools:
  depth: $DEPTH_DEFAULT
  remotes:
    origin: [***]
  target: origin $ODOO_VERSION
  merges:
    - origin $ODOO_VERSION

这意味着，只有当与标准情况有差异时，才需要在 [repos.yaml][] 中定义 git 聚合器规范：

• 需要特殊合并。
• 需要特殊远程源。
• 文件夹名称与远程源模式不匹配。
• 分支名称与 $ODOO_VERSION 不匹配。
• 等等。

/opt/odoo/custom/src/addons.yaml

每个条目对应一个仓库和您要在项目中激活的插件。示例如下：

yaml
website:
    - website_cookie_notice
    - website_legal_page
web:
    - web_responsive

高级功能：

• 若要按逻辑分组插件且某些仓库重复出现，可使用 [多个 YAML 文档][]，用 --- 分隔每个文档。

• private 和 odoo/addons 下的插件会自动链接，除非您明确指定。

• 可使用 ONLY 指定环境变量字典和允许的值列表，仅在匹配的环境中启用该文档。

• 若某个插件在多个位置存在，链接优先级如下：

  1. [private][] 中的插件。
  2. 其他仓库中的插件（若多个仓库中存在同名插件，链接结果随机，请注意避免！）。
  3. [odoo/addons][odoo] 中的 Odoo 核心插件。

• 若指定的插件在运行时不存在，会静默失败。

• 支持 [Python 的 glob 模块][] 支持的通配符。

高级功能示例：

yaml
# 西班牙语本地化
l10n-spain:
  - l10n_es # 覆盖 odoo/addons 中的内置 l10n_es
server-tools:
  - "*date*" # 所有名称含 "date" 的模块
  - auditlog
web:
  - "*" # 所有 web 插件
---
# 单独的 YAML 文档，用于分隔 SEO 工具
website:
  - website_blog_excertp_img
server-tools: # 此处重复 server-tools，没问题，因为是不同文档
  - html_image_url_extractor
  - html_text
---
# 仅在开发和测试环境启用演示 ribbon
ONLY:
  PGDATABASE: # 环境变量必须存在且值在列表中
    - devel
    - test
web:
  - web_environment_ribbon
---
# 仅在生产环境启用特殊认证方法
ONLY:
  PGDATABASE:
    - prod
server-tools:
  - auth_*

/opt/odoo/custom/dependencies/*.txt

用于指定子镜像依赖项的文件，每种包管理器对应一个文件：

• apt_build.txt：构建时依赖项，在其他依赖项之前安装，之后会被移除。通常包括 build-essential 或 python-dev 等 Debian 包。从 Doodba 11.0 开始，此文件可能不再需要，因为镜像已包含构建依赖项，且应使用本地 Python 开发头文件而非从 apt 下载。
• apt.txt：apt 安装的运行时依赖项。
• gem.txt：gem 安装的运行时依赖项。
• npm.txt：npm 安装的运行时依赖项。
• pip.txt：标准的 [pip requirements.txt][] 文件，用于运行时依赖项。会以 --update 标志执行，以便覆盖任何预捆绑的依赖项。

/opt/odoo/common：工具目录

此目录包含各种工具脚本。目前暂未详细文档，可查看代码了解。

注意事项：

• 默认使用 [PYTHONOPTIMIZE=1][] 编译代码。

• 默认移除镜像中未使用的代码（未在 /opt/odoo/custom/src/addons.yaml 中列出），以减小镜像体积。

/opt/odoo/auto：自动生成目录

此目录包含构建时自动生成的内容。

/opt/odoo/auto/addons

包含指向 [addons.yaml][] 中选择的插件的符号链接。

/opt/odoo/auto/odoo.conf

合并 /opt/odoo/{common,custom}/conf.d/ 下的所有配置文件的结果（按此顺序）。

Dockerfile

未来将文档化所有构建参数和环境变量，目前请注意：

• 这只是一个基础镜像，包含大量工具。您需要基于此构建项目子镜像，即使项目的 Dockerfile 仅包含以下两行：

  FROM tecnativa/doodba
  MAINTAINER 我 <***>
  

• 由于此镜像包含大量 ONBUILD 指令，因此项目必须包含 ./custom 文件夹才能正常工作。

• 若遵循我们的约定，一切将自动运行。只需将代码放在正确位置即可。

捆绑工具

镜像中包含多种工具，帮助处理 Odoo 的特殊性：

addons

基于当前环境自动管理插件的命令行工具。可安装、更新、测试和列出当前容器中可用的私有、额外和核心插件，基于 [addons.yaml][] 配置。

执行 addons --help 查看使用说明。

click-odoo 及相关脚本

包含优秀的 [click-odoo][] 脚本框架和 [click-odoo-contrib][] 中的脚本集合。请参考其***文档了解使用方法。

* 注意：替代已弃用的 python-odoo-shell 二进制文件。

[nano][]

常用的命令行文本编辑器，方便在热部署中检查问题。

log

用于在构建或入口点脚本中添加日志的小 shell 脚本：

log INFO 正在输出信息

pot

导出任意插件翻译模板的 shell 快捷命令。用法：

pot my_addon,my_other_addon

psql

已配置环境变量，如需连接数据库，只需执行：

docker exec -it 你的容器 psql

其他 [Postgres 客户端应用][] 也是如此。

ptvsd

[VSCode][] 调试器。若使用此编辑器及其 Python 扩展，会很有用。

要在代码中某点调试，添加以下 Python 代码：

python
import ptvsd
ptvsd.enable_attach("doodba-rocks", address=("0.0.0.0", 6899))
print("ptvsd 等待连接...")
ptvsd.wait_for_attach()

要在 ptvsd 环境中启动 Odoo（会遵循 IDE 中的断点，但运行较慢），只需向 Odoo 容器添加 -e PTVSD_ENABLE=1。

若使用*** [脚手架][]，可通过以下命令启动 ptvsd 模式：

bash
export DOODBA_PTVSD_ENABLE=1
docker-compose -f devel.yaml up -d

当然，需要正确配置 [VSCode][]。确保项目中有 .vscode/launch.json 文件，包含以下基本内容：

json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "附加到 devel.yaml 中的调试器",
            "type": "python",
            "request": "attach",
            "pathMappings":