迁移用户映射是在数据迁移中，把来源系统里的每个用户身份对应到目标系统账号的处理过程，产出物通常是一份可执行的映射表或匹配规则。它要回答“来源里的这个人，在目标系统里是谁”，并把组织归属和权限角色一并带过去。只按用户名匹配容易出错：重名、改名、大小写差异以及目标系统中不存在的账号，都会让工作项、评论和审批记录挂到错误的人名下。
要点总览（TL;DR）
- 迁移用户映射是在数据迁移中把来源系统的每个用户身份对应到目标系统账号的处理过程，产出物是一份可执行的映射表或匹配规则。
- 只按用户名匹配会因重名、改名、大小写与格式差异、目标系统无对应账号而失效，用户名可修改，不是稳定标识。
- 映射应以邮箱、工号或外部目录ID等稳定唯一标识为主匹配依据，显示名与用户名作辅助校验，并携带所属部门、团队、权限角色和账号状态。
- 映射结果通常经过提取、自动匹配、人工确认和落库四个环节，无对应账号时按新建、合并或挂起策略处理。
- 用户映射处理人的身份对应，字段映射处理数据字段与取值格式，权限迁移处理角色与访问规则还原，三者按用户、字段、权限的顺序衔接。
迁移用户映射的直接定义
迁移用户映射指建立来源系统用户与目标系统账号之间的一一对应关系。这里的“用户”既包括真实员工，也包括外部协作人员、服务账号等以账号形式存在的身份。映射的基本形态是一张表：每一行记录一个来源用户，以及它在目标系统中对应的账号、匹配依据和匹配状态。
在数据迁移流程中，用户映射属于迁移数据内容的一部分，位置先于业务数据归属处理。问题、评论、附件、审批记录等数据本身带有创建人和处理人信息，这些信息在目标系统中需要换成目标账号才能正确显示和检索。因此，用户映射通常在业务数据导入之前完成，作为后续归属转换的输入。
映射表的常见形态如下，字段可按实际系统增减：
| 来源用户 | 匹配依据 | 目标账号 | 匹配状态 |
|---|---|---|---|
| zhangsan（张三） | 邮箱 zhangsan@example.com | zhangsan | 已匹配 |
| lisi（李四） | 工号 10086 | li.si | 已匹配 |
| wangwu（王五） | 无稳定标识 | 待定 | 需人工确认 |
用户映射的范围边界：管什么、不管什么
用户映射管的是身份对应关系，以及随身份携带的组织与角色信息。具体包括：来源用户对应哪个目标账号、归属哪个部门或团队、在哪些项目中以什么角色出现、账号处于启用还是停用状态。这些信息决定迁移后的数据“归谁所有、谁能看到”。
以下事项不属于用户映射本身：
- 工作流状态、审批流转规则和插件行为的迁移，归工作流与扩展能力迁移处理。
- 迁移完成后数据是否完整、归属是否正确、系统是否可用的核验，归迁移验证与切换管理处理。
- 目标系统权限模型的重新设计，例如是否引入新的角色体系、是否调整项目权限层级，属于目标系统的配置规划，映射只负责把来源身份落到既有或已规划好的账号上。
划清这条边界的作用在于：映射做得好，只说明“人对上了”；权限是否合理、流程是否顺畅，还需要后续环节分别检查。把三者混在一起，容易在映射阶段承担不属于它的设计决策。
为什么只按用户名匹配不够
用户名是登录标识，不是稳定身份标识。它在来源系统中可以被修改，在不同系统中命名规则也不一致，因此单独作为匹配依据会产生几类典型失败。
- 重名与同名不同人。两个系统各有一个“zhangsan”，可能对应不同员工；来源系统中的“张三”和目标系统中的“张三”也可能只是同名。按用户名直接匹配会把数据挂到错误的人名下。
- 改名、大小写、空格与编码差异。员工改名后用户名可能随之变化；同一姓名在不同系统中可能写作“Zhang San”“zhang.san”“zhangsan”，全角半角、前后空格、中英文混排都会造成字符串不相等。
- 目标系统中没有对应账号。离职人员的历史数据仍需保留归属，外部协作账号往往不在目标系统的正式成员名单中，服务账号也可能没有对应的自然人账号。这些用户在目标系统中找不到匹配对象。
- 用户名可修改，不是稳定标识。即使当前匹配成功，用户名变更后映射关系也会失效。依赖用户名的映射难以复用到下一次迁移或增量同步。
这些失败共同指向一个结论：映射需要以稳定唯一标识为主依据，用户名和显示名只作辅助校验。
映射需要综合的身份标识、组织与权限信息
一份可执行的映射表应包含以下几类字段，每类字段承担不同作用。
| 字段类别 | 示例 | 作用 |
|---|---|---|
| 稳定唯一标识 | 邮箱、工号、外部目录 ID | 作为主匹配依据，跨系统不易变化 |
| 显示名与用户名 | 姓名、登录名 | 辅助校验，人工确认时便于识别 |
| 组织信息 | 所属部门、团队、用户组 | 还原组织归属，支撑按组织维度的查询与统计 |
| 权限角色 | 项目角色、系统角色、成员身份 | 延续访问控制，决定迁移后能看到哪些数据 |
| 账号状态与类型 | 启用/停用、内部/外部/服务账号 | 区分处理策略，避免把停用账号误建为活跃成员 |
稳定唯一标识优先选用邮箱或工号，是因为它们在人事系统中通常一人一号、变更受控。显示名和用户名用于人工复核：当自动匹配出现多个候选时，靠姓名和登录名快速判断。组织信息决定迁移后的数据在部门视图、团队报表中是否归位。权限角色决定访问控制能否延续，例如来源系统中的项目管理员在目标系统中应获得对应管理权限。账号状态与类型则影响处理策略：离职账号通常保留归属但停用，外部协作账号需要单独确认是否纳入目标系统。
映射的组成与执行机制
映射结果的形成通常经过提取、匹配、人工确认和落库四个环节，每个环节都有明确的输入和输出。
- 提取。从来源系统导出用户清单及属性，包括唯一标识、显示名、组织、角色和账号状态。同时从目标系统导出已有账号清单，作为匹配的另一侧数据。
- 自动匹配。按优先级规则逐级匹配：先用邮箱或工号精确匹配，再用用户名加组织等组合条件匹配。命中唯一结果的进入已匹配状态，命中多个或零个的进入冲突队列。
- 人工确认。对冲突项逐条判断。重名时结合部门、工号、历史活动记录确认身份；改名时通过邮箱等稳定标识回溯；无对应账号时确定处理策略。
- 落库。确认后的映射表作为业务数据归属转换的输入，导入时按表把来源用户替换为目标账号。
无对应账号的处理策略通常有三种：新建账号，适用于仍在职但目标系统尚未开通的人员；合并到已有账号，适用于同一人存在多个来源身份的情况；挂起或归入保留账号，适用于离职人员和无法确认归属的历史数据。策略选择取决于数据用途：需要保留审计追溯的记录，通常保留原归属并标记停用，而不是简单丢弃。
映射结果落地到目标系统后，还需要在成员与权限配置中生效。以 ONES 为例，从 Jira 迁移到 ONES Project 时，迁移范围包括用户、用户组和系统配置，系统配置涵盖问题类型、工作流、字段配置、权限配置等；从 Confluence 迁移到 ONES Wiki 时，迁移数据包括用户、用户组、空间权限与页面权限。这些官方方案说明用户与用户组是迁移内容的一部分，具体采用哪些字段匹配、冲突如何处理，需要结合项目实际情况在迁移前确认。ONES 的替换方案也把数据完整、业务连续和系统稳定作为迁移目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配。
相邻概念区别：用户映射、字段映射与权限迁移
三个概念处理的对象不同，容易在迁移方案讨论中混用。下表按处理对象、输入和产出做对照。
| 概念 | 处理对象 | 输入 | 产出 |
|---|---|---|---|
| 用户映射 | 人的身份对应 | 来源用户清单、目标账号清单 | 用户对应表，含组织与角色信息 |
| 字段映射 | 数据字段与取值格式的对应 | 来源字段定义、目标字段定义 | 字段对应规则与取值转换规则 |
| 权限迁移 | 角色与访问规则的还原 | 来源权限配置、目标权限模型 | 目标系统中的角色分配与访问规则 |
三者在顺序上存在依赖：用户映射先确定“谁是谁”，字段映射确定“数据怎么放”，权限迁移在两者基础上确定“谁能看、谁能改”。如果用户映射不完整，权限迁移就缺少分配对象；如果字段映射缺失，即使人对了，数据内容也可能错位。实际项目中三者可以并行准备，但落库和验证时通常按用户、字段、权限的顺序推进。
具体例子与常见误解
假设一个团队从来源系统迁移到目标系统，来源用户清单中有三个人：张三，用户名 zhangsan，邮箱 zhangsan@example.com；另一个张三，用户名 zhangsan2，已离职；李四，用户名 lisi，迁移前改名为李思，用户名未变但显示名已更新。目标系统中已有账号 zhangsan（对应第一个张三）和 lisi（对应李四），没有第二个张三的账号。
处理结果如下：
| 来源用户 | 匹配过程 | 处理结果 |
|---|---|---|
| 张三（zhangsan） | 邮箱精确匹配 | 对应目标账号 zhangsan，组织与角色按映射表带入 |
| 张三（zhangsan2，离职） | 用户名无匹配，邮箱无匹配 | 保留归属，标记为停用或归入保留账号，不新建活跃成员 |
| 李四（显示名已改为李思） | 用户名 lisi 匹配，显示名不一致 | 以用户名为辅、邮箱为主确认后对应 lisi，显示名以目标系统为准 |
围绕这个场景，有三个常见误解需要纠正。
- 误解一：用户名相同即同一人。上例中两个张三用户名不同，但现实中同名同用户名的情况并不少见。用户名只是登录名，判断身份要回到邮箱、工号等稳定标识，并结合组织信息交叉验证。
- 误解二：映射完成等于权限正确。映射只保证人对应上了，权限是否正确取决于角色信息是否完整带入、目标系统权限模型是否匹配。映射完成后仍需单独核对关键项目的成员和访问范围。
- 误解三：外部协作账号可以忽略。外部协作人员的历史评论、附件和审批记录同样需要归属。忽略这类账号会导致数据出现无主记录，影响审计和追溯。正确做法是单独列出外部账号，确认是否在目标系统中建立对应身份，或归入统一的保留账号。
把映射表当作迁移方案中的独立交付物来准备，明确字段、匹配优先级和冲突处理规则，可以让后续的数据导入和权限配置有据可依，也便于在迁移验证阶段逐条核对归属是否正确。
常见问题
迁移时来源用户和目标账号的邮箱不一致，还能用邮箱做主匹配依据吗？
邮箱作为主匹配依据的前提是它在两侧指向同一个人。如果来源系统记录的是个人邮箱、目标系统登记的是企业邮箱，直接精确匹配会失败。此时可以把邮箱匹配降为辅助条件，改用工号或外部目录 ID 做主匹配；没有稳定标识时，用“姓名＋部门＋历史活动记录”组合判断，并进入人工确认队列。迁移前先抽样比对两侧邮箱的命名规则，能减少这类冲突。
离职人员和外部协作账号在映射中应该怎么处理？
这两类账号的共同点是目标系统中往往没有活跃成员身份，但历史数据仍需要归属。常见做法是保留原归属并标记停用，或归入统一的保留账号，避免出现无主记录影响审计追溯。外部协作账号需要单独列出，确认是否在目标系统中建立对应身份；如果建立，还要明确其可见范围。处理策略取决于数据用途，需要长期追溯的记录不宜简单丢弃。
映射表做完之后，权限是否就自动正确了？
映射只保证“人对上了”，权限是否正确还取决于角色信息是否完整带入、目标系统的权限模型是否匹配。例如来源系统中的项目管理员角色，在目标系统中需要有对应的角色或权限组承接。映射完成后，建议单独核对关键项目的成员名单和访问范围，把权限核对作为迁移验证的一部分，而不是默认映射结果等于权限结果。
增量迁移或后续同步时，已有的用户映射还能复用吗？
能否复用取决于映射依据是否稳定。以邮箱、工号等稳定标识建立的映射，在人员信息小幅变动时通常可以继续使用；以用户名或显示名建立的映射，遇到改名或命名规则调整就会失效。复用前建议先比对增量用户清单与已有映射表，识别新增用户、标识变更用户和已离职用户，再决定沿用、修正或新增映射记录。
ONES 在迁移中如何处理用户和用户组？
根据 ONES 官方迁移方案，从 Jira 迁移到 ONES Project 时，迁移范围包括用户、用户组和系统配置，系统配置涵盖问题类型、工作流、字段配置、权限配置等；从 Confluence 迁移到 ONES Wiki 时，迁移数据包括用户、用户组、空间权限与页面权限。具体采用哪些字段做匹配、冲突如何逐条处理，需要结合项目实际情况在迁移前确认。
