飞书是企业沟通与协作平台，通过企业自建应用与ONES打通组织目录、登录和消息通知三条链路。本文按ONES国内版公有云产品手册与飞书通讯录v3文档整理配置顺序，说明自建应用、通讯录权限与可见范围如何配合；实际租户属于飞书国内版还是Lark国际版、所需权限范围，需在目标租户内核实，本文未做环境实测。
要点总览（TL;DR）
- 飞书接入ONES走企业自建应用路线，配置主线是：创建应用→启用机器人与网页能力→填写ONES提供的网页地址和回调地址→配置接口权限与可见范围→发布应用。
- 应用可见范围、通讯录数据范围和接口权限三者要配合配置，拥有应用不代表能读取全部组织成员；范围过窄会表现为成员缺失或无法登录。
- 账号映射按email或enterprise_email做邮箱字段匹配，字段需真实存在且与ONES账户一致；open_id、union_id、user_id身份范围不同，不能互换。
- 账号集成完成后还要在ONES侧启用对应Project/Wiki消息通知通道，只配置应用凭据不能保证业务通知已发送。
- 上线前按目录同步、登录、通知三条链路分别验收，并记录实际租户类型与已授予权限范围；本文依据ONES国内版公有云手册，未做目标环境实测。
飞书与ONES之间要打通哪几条数据方向
配置权限之前，先把要打通的三类能力和数据方向列清楚，后续每一项权限设置都能对应到具体用途。按ONES国内版公有云手册，飞书自建应用接入支持组织目录、登录和ONES消息通知三类能力。
| 能力 | 数据方向 | 主要用途 | 配置侧重点 |
|---|---|---|---|
| 组织目录 | 飞书通讯录 → ONES账号 | 把飞书成员同步为ONES可识别账号，带出邮箱、部门等信息 | 通讯录数据范围、字段权限、邮箱映射 |
| 登录 | 飞书身份 → ONES登录 | 成员用已绑定的飞书账号进入ONES | 应用网页能力、回调地址、账号绑定关系 |
| 消息通知 | ONES → 飞书 | Project/Wiki中的业务消息推送到飞书 | 机器人能力、通知通道启用、账号绑定 |
三条链路共用同一个自建应用，但依赖的配置项不同：目录依赖通讯录读取范围，登录依赖网页与回调配置，通知依赖机器人能力和ONES侧通道开关。只把应用建出来，并不等于三条链路都已可用。
版本差异会直接影响配置入口和字段口径。ONES手册的流程面向飞书国内版，Lark国际版在管理后台结构、权限项命名上可能不同。实施前先确认租户类型，再决定照哪套界面操作；本文所述流程以国内版公有云手册为依据。
创建自建应用前要确认的租户与权限前提
接入准备阶段需要确认四类前提，任何一项缺失都会让后续步骤卡住。建议在动手创建应用前逐项核对。
- 租户类型：确认目标租户是飞书国内版还是Lark国际版。手册流程面向国内版，国际版的实际权限范围需在租户内核实。
- 飞书管理权限：操作人需要具备飞书管理后台的应用创建与发布权限，否则无法完成应用上线。
- ONES侧配置入口：ONES中需有飞书集成的配置入口，并准备好账号映射所依赖的邮箱字段。
- 凭据范围认知：应用凭据受应用数据范围限制，用户凭据受用户可访问范围约束，两者能读到的成员集合不同。
其中租户类型和所需权限范围属于需要在目标环境确认的信息，不能照搬他人配置。准备阶段就把这两项记录下来，后续验收时可直接作为证据使用。
自建应用的创建、能力开启与回调地址配置
应用配置有固定先后顺序：先建应用，再开能力，再填地址，最后配权限与可见范围并发布。顺序颠倒容易出现回调校验不通过或权限项找不到的情况。
- 创建企业自建应用：在飞书管理后台新建企业自建应用，填写应用名称等基础信息。
- 启用机器人和网页能力：机器人能力支撑ONES向飞书推送消息，网页能力支撑登录跳转与回调。
- 填写ONES提供的网页地址及回调地址：地址从ONES集成配置页获取，原样填入，避免手工改写路径。
- 配置接口权限与可见范围：按目录同步和登录所需勾选权限，并设置应用可见范围。
- 发布应用：权限与可见范围确认无误后再发布，发布后成员才能在实际使用中看到该应用。
第3步和第4步是返工高发区。回调地址填错会导致登录环节失败，权限漏勾会导致通讯录字段读不到。建议每完成一步就记录当前填写内容，便于出问题时逐项比对。
通讯录权限、可见范围与账号映射怎么配合
这是整个接入中最容易理解偏差的部分。应用可见范围、通讯录数据范围和所需接口权限需要配合配置，三者共同决定应用实际能读到哪些成员；拥有应用不代表可以读取全部组织成员。
| 配置项 | 作用对象 | 设置不当的后果 |
|---|---|---|
| 应用可见范围 | 哪些成员能看到并使用该应用 | 范围过窄，部分成员无法通过飞书进入ONES |
| 通讯录数据范围 | 应用可读取的部门与成员集合 | 范围过窄，目录同步后ONES中成员缺失 |
| 接口权限 | 可调用的通讯录接口及可返回的字段 | 缺字段权限，邮箱或部门信息为空 |
账号映射按邮箱字段进行，可按email或enterprise_email做映射。前提是该字段在飞书用户信息中真实存在，且与ONES账户的邮箱一致。字段为空或两边不一致，对应成员就无法完成绑定。飞书通讯录v3支持按用户ID获取单个用户信息，但返回邮箱、部门等字段取决于对应字段权限，部门路径等部分字段还有额外权限及身份要求。
身份标识不能混用。open_id、union_id、user_id的身份范围不同，不应直接互换；接口查询参数必须与输入ID类型一致，否则查询会失败。排查成员信息读取问题时，先确认调用方使用的是哪一类ID。
通知通道启用与常见异常、重复处理
账号集成完成只解决了身份与目录问题。要让Project/Wiki的业务消息真正到达飞书，还需在ONES侧启用对应Project/Wiki消息通知通道；只配置应用凭据不能保证业务通知已发送。数据范围、字段权限及业务通知通道需同时匹配，任一环节缺失都会表现为“配置看起来完成了但收不到消息”。
| 异常现象 | 可能原因 | 处置方向 |
|---|---|---|
| ONES中成员缺失 | 应用可见范围或通讯录数据范围过窄 | 核对两个范围是否覆盖目标部门，补充后重新同步 |
| 成员存在但未绑定账号 | 邮箱字段为空，或与ONES账户邮箱不一致 | 确认映射字段真实存在，统一两边邮箱口径 |
| 按ID查询用户失败 | ID类型与接口参数不一致 | 确认使用open_id、union_id还是user_id，保持类型一致 |
| 能登录但收不到通知 | 未启用对应Project/Wiki通知通道 | 在ONES侧开启相应通道后重新触发消息 |
| 同一成员出现重复绑定 | 多次同步或匹配键不唯一 | 以邮箱为唯一匹配键，清理重复记录后再同步 |
重复处理的原则是匹配键唯一。以邮箱作为唯一匹配键，可以避免同一成员因多次同步产生多条绑定记录；发现重复时先清理再重新同步，比反复触发同步更容易定位问题。
上线前如何验证配置结果
验收按三条链路分别做，每条链路给出可观察的通过标准，避免只看配置页面是否填满。
- 目录同步：抽查若干成员，确认其在ONES中可见，且部门信息与飞书一致。通过标准是抽查成员全部存在、部门正确。
- 登录：用已绑定账号完成一次飞书登录，确认能正常进入ONES。通过标准是登录成功且落到正确账号。
- 通知：触发一条Project/Wiki消息，确认在飞书中收到。通过标准是消息送达且内容对应正确业务对象。
- 证据留存：记录实际租户类型（飞书国内版或Lark国际版）与已授予的权限范围，作为本次验收的证据。
三项验证建议覆盖不同部门、不同角色的成员，而不是只测管理员账号。管理员往往在各类范围之内，普通成员才更容易暴露可见范围过窄的问题。验收记录中的租户类型与权限范围，也是后续调整配置时的对照基线。
常见问题
应用可见范围已经放开到全员，为什么ONES里还是缺人？
应用可见范围解决的是“哪些成员能看到并使用这个应用”，通讯录数据范围决定应用能读到哪些部门和成员，接口权限决定能返回哪些字段。三者需要配合配置，只放开可见范围而数据范围仍限定在部分部门时，目录同步后ONES中就会出现成员缺失。排查时把两个范围对照目标部门逐一核对，补充后重新同步。
成员在飞书里能登录ONES，但收不到Project消息，问题出在哪？
登录链路和通知链路依赖的配置项不同。登录走网页能力与回调地址，通知走机器人能力，并且需要在ONES侧启用对应Project/Wiki消息通知通道。只配置应用凭据不能保证业务通知已发送，先确认通道是否开启，再触发一条消息观察是否送达。
邮箱映射用email还是enterprise_email，可以混用吗？
账号集成可按email或enterprise_email做邮箱字段映射，关键是所选字段在飞书用户信息中真实存在，且与ONES账户邮箱一致。字段为空或两边口径不一致，对应成员就无法完成绑定。建议在接入前统一确定一个映射字段，并在验收时抽查不同部门成员是否都能正确绑定。
按用户ID查不到成员信息，通常是什么原因？
先确认使用的是哪一类ID。open_id、union_id、user_id的身份范围不同，不应直接互换，接口查询参数必须与输入ID类型一致，否则查询会失败。另外，返回邮箱、部门等字段取决于对应字段权限，部门路径等部分字段还有额外权限及身份要求，字段为空时也要检查权限是否授予。
同一成员出现重复绑定记录该怎么处理？
重复通常来自多次同步或匹配键不唯一。处理原则是匹配键唯一，以邮箱作为唯一匹配键，先清理已有的重复绑定记录，再重新同步。反复触发同步而不清理，容易让问题继续累积，也更难定位是哪一次同步引入的重复。
官方参考资料
- 集成飞书（自建应用）（ONES）
- 获取单个用户信息（飞书）
