> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/yong-hu-he-xiang-mu-guan-li/user-management/username-migration.md).

# 用户名迁移

## 用户名迁移

从登录的角度来看，用户的主要标识符是其电子邮件地址。如果你正在从本地身份验证迁移到 SSO，或者正在从一个 IdP 迁移到另一个 IdP，你可能需要更新用户的电子邮件地址。

为帮助完成此操作，提供了一个脚本，可使用以下格式的 CSV 文件迁移用户邮箱：

`oldEmail,newEmail`

在进行一些验证检查后，脚本将遍历 CSV 文件，并将用户的电子邮件地址从 `oldEmail` 到 `newEmail`.

### **验证**

在运行迁移之前， `<csv_file>` 将被检查以确保：

* 对于每一行， `oldEmail` 以及 `newEmail` 都是有效的电子邮件地址
* 不存在重复条目，例如，你没有尝试将不同用户更新为同一个新电子邮件地址，或者你没有尝试使用一个已被使用的电子邮件地址来更新同一个用户账户

### **用法** <a href="#usage" id="usage"></a>

{% code overflow="wrap" %}

```bash
docker cp <csv_file> sharelatex:/overleaf/services/web/<csv_file> docker exec sharelatex /bin/bash -c "cd /overleaf/services/web;node ./modules/server-ce-scripts/scripts/migrate-user-emails.js [--commit] [--continue|--ignore-missing] [--admin-id=ADMIN_USER_ID] <csv_file>"
```

{% endcode %}

### **标志** <a href="#flags" id="flags"></a>

| 名称                 | 描述                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `--commit`         | <p>包含 <code>--commit</code> 标志将真正执行迁移。若省略，则迁移将以试运行模式进行，不会做出任何更改，但仍会执行验证。<br><br><strong>默认</strong>:<code>false</code></p> |
| `--continue`       | 该 `--continue` 标志将在用户账户的电子邮件地址已被更新的情况下继续迁移过程                                                                               |
| `--ignore-missing` | 该 `--ignore-missing` 标志将在未找到用户账户的情况下继续迁移过程                                                                                 |
| `--admin-id`       | 该 `--admin-id` 应设置为执行迁移的管理员 ID，并将用于审计日志条目。前往 **管理员** > **管理用户** 并搜索你的电子邮件地址，然后点击第一个结果以找到你的 user-id。                        |
| `<csv_file>`       | 该 `<csv_file>` 是包含旧电子邮件地址和新电子邮件地址的文件，格式为                                                                                   |

### **完成** <a href="#completion" id="completion"></a>

在执行迁移脚本时，取决于你选择的标志，将决定是将错误记录到控制台后继续，还是记录到控制台后退出。如果脚本因错误而提前终止，它将以代码 1 退出，以表明迁移失败。

迁移完成后，脚本将把成功、失败和跳过的更新数量记录到控制台。如果迁移成功完成，它将以代码 0 退出。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/zh-cn/yong-hu-he-xiang-mu-guan-li/user-management/username-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.