导读：为什么文件字段在 Odoo 中不可忽视
二进制字段看起来不起眼，却在日常 Odoo 项目中无处不在——从客户记录上上传的签署合同，到商品档案的技术说明，再到企业 logo 的保存，背后都是二进制字段在存取文件。弄清楚它如何保存数据、数据最终存在哪里、以及什么时候应该换用其他字段类型，对设计表单和扩展模型时的性能、可维护性和用户体验都有显著影响。
本文将说明二进制字段保存什么内容、附件模式如何影响存储与性能、如何通过 Odoo Studio 或 Python 创建与定制该字段，并结合 CRM、HR、库存等多个业务场景讲解实用做法。
什么是 Odoo 的二进制字段（Binary）
在 Odoo 的 ORM 里，Binary（fields.Binary）用于保存原始二进制内容：各种文件、文档和图像等。对终端用户来说，它在表单上表现为一个上传/下载控件；上传后同一个控件可以一键下载已附加的文件。
最关键的技术点是“文件实际存放在哪里”。现代 Odoo 默认采用附件模式（attachment），即文件内容存放在 ir.attachment 记录和服务器的 filestore 中，模型表的那一列仅保存指向附件的引用 ID。这样可以让主要业务表保持精简，并借助 Odoo 的文件存储机制高效管理文件。
在 Odoo Studio 中，二进制字段以“File”（文件）名称出现，拖入表单后会渲染为上传/下载控件。若处理的是图片，Odoo 还提供了专用的 fields.Image 类型，能自动生成缩略图并按最大尺寸限制图片，这一点在图像场景尤为重要。
下面给出一个在 Python 模型中定义二进制字段的示例（示意用）——
示例展示了如何在已有模型上新增一个二进制字段并配套一个用于保存原始文件名的字符串字段。实际工程中建议总是加上文件名字段以保留原来文件名，避免用户下载时得到不可识别的通用名称。
配套的 _filename 字段并非可选：它用来在界面展示并在下载时恢复原始文件名。没有这个字段，用户通常会得到一个类似“download”的默认文件名，体验较差。
二进制字段的工作原理概览
在模块安装或升级时，Odoo 会自动为模型生成所需的数据库列，通常无需手写 SQL。开发者只需在 Python 中声明字段，部署流程会处理剩余工作。
存储模式详解
Binary 字段的 attachment 参数决定文件字节的实际存放位置：
- attachment=True（推荐）：文件内容作为 ir.attachment 记录保存，并在服务器 filestore 中存放实际文件。模型字段仅保存对该附件的引用 ID。这能保持业务表小巧并利用 Odoo 的文件管理优势。
- attachment=False：文件内容以 base64 编码的字符串直接写入模型的数据库列。此方式会迅速膨胀表体积，影响查询性能，只适合极小的缩略图片或非常受限的场景。
数据格式说明
二进制字段读写时使用 base64 编码的字符串。通过 ORM 或 XML-RPC 读取字段会得到 base64 字符串；写入时也必须提供 base64 编码后的内容。
这意味着在代码中写入前需要对文件内容进行 base64 编码，读取后再解码为字节流以供保存为文件或进一步处理。
示例通常用如下流程：用 base64.b64encode 编码写入，用 base64.b64decode 解码读取。注意在代码中要处理空值（False）的情况，见后文常见错误一节。
常用字段属性速览
以下属性是定义 Binary 字段时最常用也最重要的配置：
- attachment：布尔值。是否使用 ir.attachment 存储（True）或直接写入列（False）。在新版本中默认是 True。
- string：界面显示的标签文字。
- required：是否为必填字段，保存记录前必须有值。
- compute：用于将字段值通过方法动态计算（例如运行时生成 PDF）。
- store：与 compute 配合时决定是否将计算结果持久化到数据库。
- groups：限制字段可见/可写的用户组，用于敏感文件的访问控制。
- copy：控制复制记录时字段是否被复制，不同附件模式下默认值可能不同。
fields.Image：为图片量身定制的子类
fields.Image 是从 Odoo 13 起引入的针对图像的二进制子类，能自动按配置的最大尺寸调整图片、生成预览缩略图，并在表单中直接显示图像预览。存储产品图、员工头像或公司标识时优先使用 fields.Image，它既能防止上传超大图片，也能提升界面体验。
在视图中的呈现方式
在表单视图里，Binary 字段默认渲染为上传/下载控件；若是图片可使用 image widget 显示缩略图。列表视图一般不直接展示二进制内容，以免为每一行拉取大量数据；常见做法是用计算布尔字段或图标来提示是否有附件。
常见的业务场景与应用
以下列举了在真实业务中经常出现的五类二进制字段应用场景，帮助你把理论落地到实际需求。
CRM 场景：在客户记录上保存签署的保密协议或合同
销售团队常需要把签署文件附在客户或商机记录上以便随时查看。把二进制字段放在 res.partner 或 crm.lead 上，销售人员可以在同一界面打开合同，省去切换到独立文档管理系统的麻烦，也能在销售流程中把关键文档和客户信息紧密绑定。
HR 场景：员工证件与合约资料存档
人事部门需要保存员工身份证件、工作许可、签署合同或培训证书等敏感文件。把这些文件放在 hr.employee 的二进制字段，并通过 groups 限制访问，可以把文件纳入 Odoo 的权限体系，确保只有获权人员能查看，满足企业合规与隐私保护的要求。
库存场景：产品规格书与安全数据表
制造与分销企业常常需要在产品档案上保存厂家的技术规格书、物料安全数据表或质量证书。把这些文件存到 product.template 上，让采购和仓库人员在处理采购单或出入库时能快速查看对应文档，能显著提高日常操作效率。
销售文档：印刷报价上的公司章或签名图片
某些业务需要在打印的报价或订单上自动带上公司章或授权签名。把印章/签名以 fields.Image 存在 res.company 上，然后在 QWeb 模板中引用，可以实现自动化印章插入，减少人工处理并避免遗漏签名的风险。
会计报销：报销单附上发票或收据的扫描件
报销审批流程通常要求在每笔费用上附上凭证图片或发票 PDF。标准的附件系统可以满足大多数需求，但在自定义费用模型或与第三方集成时，直接在记录上增加 Binary 字段并将其纳入审批逻辑能带来更清晰的流程控制。
如何创建或定制二进制字段
为模型添加二进制字段有三种常用方式，选择哪种取决于你是否愿意写代码、是否需要版本控制以及部署方式。
方式一：使用 Odoo Studio（零代码）
Odoo Studio 是内置的低代码/无代码工具，适合业务用户快速在表单上增加文件上传控件。具体步骤很简单：
- 从主菜单打开 Odoo Studio。
- 定位到你想修改的表单页面。
- 从字段面板中拖入“File”（文件）控件到表单中。
- 在属性面板设置标签和可见性等选项。
- 保存并退出 Studio。
Studio 会为字段自动加上 x_studio_ 前缀并默认使用附件模式，部署方便且无需数据库层面的手工操作，是业务快速交付的常用方法。
方式二：在自定义模块中用 Python 定义
对于需要版本控制、重复部署或纳入正规开发流程的场景，应在自定义模块里用 Python 定义字段，这是更规范的做法：
示例显示了如何在 hr.employee 上添加一个受限权限的 ID 文档字段，并配套一个保存文件名的 Char 字段。把字段声明写入模块后，通过视图 XML 将其放到表单中即可。
字段声明完后，在表单视图里用 binary 小部件并通过 filename 属性指向配套的 Char 字段。安装或升级模块时 Odoo 会自动创建数据库列，这种方式适用于 Odoo.sh、私有部署或任何需要可控部署流程的环境。
方式三：通过 XML-RPC API 编程创建字段
在需要通过脚本、远程配置或自动化部署创建字段的场景下，你可以用 XML-RPC 调用 ir.model.fields 接口创建二进制字段：
通过 API 创建字段时需要指定字段名、字段说明、所属模型和类型（ttype='binary'）等信息。
使用 state='manual' 可以告诉 Odoo 这是人工创建的字段。当前 Odoo 版本下通过 API 创建的字段默认也会使用附件模式，适合自动化配置或远程部署流程。
实用最佳实践要点
最佳实践一：始终使用 attachment=True
除非有非常特殊并且经过验证的理由，否则应使用附件模式。它能保持模型表体积小、避免慢查询，并利用 Odoo 的 filestore 管理大文件。对于除小缩略图以外的任何文件，attachment=True 几乎是必须的。
最佳实践二：始终配套一个文件名的 Char 字段
二进制字段旁边添加一个以 _filename 命名的 Char 字段，可以保存原始文件名并在下载时恢复显示。这个小配置能显著提升用户体验，避免下载时出现匿名文件名。
最佳实践三：图像用 fields.Image
对于产品图、员工照或公司标识等视觉内容，应使用 fields.Image 而非普通 Binary。Image 会自动限制尺寸、生成预览图并改善界面展示，能避免用户上传超大图片导致的性能与存储问题。
最佳实践四：用 groups 控制敏感文件的访问
把员工资料、签署合同或财务凭证等敏感文件的读写权限通过 groups 参数限制到特定用户组，是满足合规与审计要求的基础做法。
最佳实践五：在代码中正确处理 base64 编码
程序读写二进制字段时必须显式处理 base64：写入前用 base64.b64encode(file_bytes).decode('utf-8')，读取后用 base64.b64decode(field_value) 解码。不要假设数据已经是你需要的格式，这类处理错误是集成时常见的 bug 来源。
常见错误与陷阱
配置错误示例：将大型文件直接写入数据库列（attachment=False）
把文件以 attachment=False 存入模型列会让 PostgreSQL 表快速膨胀。几个 PDF 就可能让单个表增加数百兆，拖慢所有针对该模型的查询。把已经以这种方式累积的数据迁移到附件模式会非常麻烦，需要编写脚本并认真规划停机迁移。
忘记配套文件名字段的问题
缺少配套的文件名 Char 字段会导致用户下载时拿到一个通用名字，给人一种功能未完善的感觉。这个问题修复成本极低，应作为任何面向用户表单的二进制字段定义的必备项。
混淆 Binary 与 Image 字段
用 Binary 存图像会丢失自动缩放与预览功能，可能允许上传超大图片；反过来用 fields.Image 存非图片文件（如 PDF）则会出错。区分这两类字段，并为不同内容选择合适的类型是基本原则。
在列表视图中直接显示 Binary 字段的性能问题
把 Binary 字段放到列表视图会导致为每一行加载完整文件内容——在记录很多时会传输大量数据并显著拖慢页面渲染。列表里应用图标或计算布尔字段来提示是否有附件，而不是直接展示二进制字段。
在代码里未先判断字段是否为 False 即处理
空的 Binary 字段在 Python 中的值是 False，而不是空字符串或空字节流。对 False 值直接解码会抛出 TypeError。编程时须先检查：if record.x_document: data = base64.b64decode(record.x_document)。这一点在 compute 方法、服务器动作和集成代码中特别容易出错。
总结：把二进制字段用好，系统更稳健
结论：二进制字段虽简单，但至关重要
二进制字段是 Odoo 数据模型里处理文件与文档的基石。养成几项好习惯：使用附件模式、配套文件名字段、为图片使用 fields.Image、对敏感文件限制访问并在代码中正确处理 base64，可以提前避免大多数生产环境中会遇到的问题。
无论是用 Odoo Studio 增加上传控件，还是在自定义模块中写 Python 字段，或通过 ORM/API 自动化创建字段，正确设计和配置二进制字段都会让你的 Odoo 实施更干净、更稳定、更易维护。
关于我们：Dasolo 在 Odoo 实施与优化方面的支持 如果你需要在项目中设计合适的数据模型、搭建文件管理流程或开发整套模块，我们的团队可以提供咨询和落地实现服务。 联系我们，聊聊你的 Odoo 项目需求。