SQL 数据同步的 Data Sync AgentData Sync Agent for SQL Data Sync

适用于: Azure SQL 数据库

通过在 Azure 中安装并配置 SQL 数据同步的 Data Sync Agent 来将数据与 SQL Server 数据库进行同步。Sync data with SQL Server databases by installing and configuring the Data Sync Agent for SQL Data Sync in Azure. 有关 SQL 数据同步的详细信息,请参阅使用 SQL 数据同步跨多个云和本地数据库同步数据For more info about SQL Data Sync, see Sync data across multiple cloud and on-premises databases with SQL Data Sync.

重要

目前,SQL 数据同步不支持 Azure SQL 托管实例。SQL Data Sync does not support Azure SQL Managed Instance at this time.

下载并安装Download and install

若要下载 Data Sync Agent,请转到 SQL Data Sync AgentTo download the Data Sync Agent, go to SQL Data Sync Agent.

以无提示方式安装Install silently

若要从命令提示符以无提示方式安装 Data Sync Agent,请输入类似于以下示例的命令。To install the Data Sync Agent silently from the command prompt, enter a command similar to the following example. 检查下载的 .msi 文件的文件名,并为 TARGETDIRSERVICEACCOUNT 参数提供你自己的值。Check the file name of the downloaded .msi file, and provide your own values for the TARGETDIR and SERVICEACCOUNT arguments.

  • 如果没有为 TARGETDIR 提供值,则默认值为 C:\Program Files (x86)\Microsoft SQL Data Sync 2.0If you don't provide a value for TARGETDIR, the default value is C:\Program Files (x86)\Microsoft SQL Data Sync 2.0.

  • 如果提供 LocalSystem 作为 SERVICEACCOUNT 的值,请在配置代理来连接到 SQL Server 时使用 SQL Server 身份验证。If you provide LocalSystem as the value of SERVICEACCOUNT, use SQL Server authentication when you configure the agent to connect to SQL Server.

  • 如果提供域用户帐户或本地用户帐户作为 SERVICEACCOUNT 的值,则还必须使用 SERVICEPASSWORD 参数提供密码。If you provide a domain user account or a local user account as the value of SERVICEACCOUNT, you also have to provide the password with the SERVICEPASSWORD argument. 例如,SERVICEACCOUNT="<domain>\<user>" SERVICEPASSWORD="<password>"For example, SERVICEACCOUNT="<domain>\<user>" SERVICEPASSWORD="<password>".

msiexec /i "SQLDataSyncAgent-2.0-x86-ENU.msi" TARGETDIR="C:\Program Files (x86)\Microsoft SQL Data Sync 2.0" SERVICEACCOUNT="LocalSystem" /qn

将数据与 SQL Server 数据库进行同步Sync data with a SQL Server database

若要配置 Data Sync Agent 来将数据与一个或多个 SQL Server 数据库进行同步,请参阅添加 SQL Server 数据库To configure the Data Sync Agent so you can sync data with one or more SQL Server databases, see Add a SQL Server database.

Data Sync Agent 常见问题解答Data Sync Agent FAQ

为什么需要客户端代理Why do I need a client agent

SQL 数据同步服务通过客户端代理与 SQL Server 数据库进行通信。The SQL Data Sync service communicates with SQL Server databases via the client agent. 此安全功能可防止与防火墙后的数据库进行直接通信。This security feature prevents direct communication with databases behind a firewall. SQL 数据同步服务与代理通信时,使用加密连接和唯一令牌或代理密钥来执行此操作。When the SQL Data Sync service communicates with the agent, it does so using encrypted connections and a unique token or agent key. SQL Server 数据库使用连接字符串和代理密钥对代理进行身份验证。The SQL Server databases authenticate the agent using the connection string and agent key. 这种设计为数据提供高度安全性。This design provides a high level of security for your data.

可以运行多少个本地代理 UI 实例How many instances of the local agent UI can be run

只能运行一个 UI 实例。Only one instance of the UI can be run.

如何更改服务帐户How can I change my service account

安装客户端代理后,更改服务帐户的唯一方法是卸载它,然后使用新的服务帐户安装新的客户端代理。After you install a client agent, the only way to change the service account is to uninstall it and install a new client agent with the new service account.

如何更改我的代理密钥How do I change my agent key

一个代理只能使用一次代理密钥。An agent key can only be used once by an agent. 删除并重新安装新代理后,不能重复使用它,它也不能被多个代理使用。It cannot be reused when you remove then reinstall a new agent, nor can it be used by multiple agents. 如果需要为现有代理创建新密钥,必须确保使用客户端代理和 SQL 数据同步服务记录相同密钥。If you need to create a new key for an existing agent, you must be sure that the same key is recorded with the client agent and with the SQL Data Sync service.

如何停用客户端代理How do I retire a client agent

若要立即使代理失效或停用代理,请在门户中重新生成其密钥,但不要在代理 UI 中提交。To immediately invalidate or retire an agent, regenerate its key in the portal but do not submit it in the Agent UI. 无论相应的代理处于联机还是脱机状态,重新生成密钥都会使以前的密钥失效。Regenerating a key invalidates the previous key irrespective if the corresponding agent is online or offline.

如何将客户端代理移至另一台计算机How do I move a client agent to another computer

如果想要从另一台计算机上运行本地代理,请执行以下操作:If you want to run the local agent from a different computer than it is currently on, do the following things:

  1. 在所需的计算机上安装代理。Install the agent on desired computer.
  2. 登录 SQL 数据同步门户,为新代理重新生成代理密钥。Log in to the SQL Data Sync portal and regenerate an agent key for the new agent.
  3. 使用新代理的 UI 提交新代理密钥。Use the new agent's UI to submit the new agent key.
  4. 客户端代理下载以前已注册的本地数据库列表时,请稍候。Wait while the client agent downloads the list of on-premises databases that were registered earlier.
  5. 为显示为无法访问的所有数据库提供数据库凭据。Provide database credentials for all databases that display as unreachable. 这些数据库必须可从安装代理的新计算机上访问。These databases must be reachable from the new computer on which the agent is installed.

解决 Data Sync Agent 问题Troubleshoot Data Sync Agent issues

客户端代理安装、卸载或修复失败The client agent install, uninstall, or repair fails

  • 原因Cause. 许多情况会导致这种失败。Many scenarios might cause this failure. 若要确定具体原因,请查看日志。To determine the specific cause for this failure, look at the logs.

  • 解决方法Resolution. 若要找到失败的具体原因,请生成并查看 Windows Installer 日志。To find the specific cause of the failure, generate and look at the Windows Installer logs. 可以在命令提示符下启用日志记录。You can turn on logging at a command prompt. 例如,如果下载的安装文件为 SQLDataSyncAgent-2.0-x86-ENU.msi,请使用以下命令行生成并检查日志文件:For example, if the downloaded installation file is SQLDataSyncAgent-2.0-x86-ENU.msi, generate and examine log files by using the following command lines:

    • 对于安装:msiexec.exe /i SQLDataSyncAgent-2.0-x86-ENU.msi /l*v LocalAgentSetup.LogFor installs: msiexec.exe /i SQLDataSyncAgent-2.0-x86-ENU.msi /l*v LocalAgentSetup.Log

    • 对于卸载:msiexec.exe /x SQLDataSyncAgent-2.0-x86-ENU.msi /l*v LocalAgentSetup.LogFor uninstalls: msiexec.exe /x SQLDataSyncAgent-2.0-x86-ENU.msi /l*v LocalAgentSetup.Log

      也可以对 Windows Installer 执行的所有安装启用日志记录。You can also turn on logging for all installations that are performed by Windows Installer. Microsoft 知识库文章如何启用 Windows Installer 日志记录提供了启用 Windows Installer 的日志记录的一键式解决方案。The Microsoft Knowledge Base article How to enable Windows Installer logging provides a one-click solution to turn on logging for Windows Installer. 此外它还提供了日志的位置。It also provides the location of the logs.

取消卸载后,客户端代理无法正常运行The client agent doesn't work after I cancel the uninstall

即使取消卸载,客户端代理仍然无法正常运行。The client agent doesn't work, even after you cancel its uninstallation.

  • 原因Cause. 出现此问题的原因是 SQL 数据同步客户端代理未存储凭据。This occurs because the SQL Data Sync client agent doesn't store credentials.

  • 解决方法Resolution. 可尝试以下两种解决方法:You can try these two solutions:

    • 使用 services.msc 重新输入客户端代理的凭据。Use services.msc to reenter the credentials for the client agent.
    • 卸载此客户端代理并安装新代理。Uninstall this client agent and then install a new one. 下载中心下载和安装最新的客户端代理。Download and install the latest client agent from Download Center.

代理列表中未列出我的数据库My database isn't listed in the agent list

尝试将现有 SQL Server 数据库添加到同步组时,代理列表中未显示该数据库。When you attempt to add an existing SQL Server database to a sync group, the database doesn't appear in the list of agents.

以下情况可能会导致此问题:These scenarios might cause this issue:

  • 原因Cause. 客户端代理和同步组位于不同的数据中心。The client agent and sync group are in different datacenters.

  • 解决方法Resolution. 客户端代理和同步组必须位于同一个数据中心。The client agent and the sync group must be in the same datacenter. 可使用以下两个选项实现这种设置:To set this up, you have two options:

    • 在同步组所在的数据中心创建新代理。Create a new agent in the datacenter where the sync group is located. 然后,将数据库注册到该代理。Then, register the database with that agent.
    • 删除当前同步组。Delete the current sync group. 然后,在代理所在的数据中心重新创建同步组。Then, re-create the sync group in the datacenter where the agent is located.
  • 原因Cause. 客户端代理的数据库列表不是最新的。The client agent's list of databases isn't current.

  • 解决方法Resolution. 停止客户端代理服务,然后重新启动该服务。Stop and then restart the client agent service.

    本地代理仅在首次提交代理密钥时下载关联的数据库列表。The local agent downloads the list of associated databases only on the first submission of the agent key. 以后提交代理密钥时,它不会下载关联的数据库列表。It doesn't download the list of associated databases on subsequent agent key submissions. 在代理移动期间注册的数据库不会显示在原始代理实例中。Databases that are registered during an agent move don't show up in the original agent instance.

客户端代理未启动(错误 1069)Client agent doesn't start (Error 1069)

发现代理未在托管 SQL Server 的计算机上运行。You discover that the agent isn't running on a computer that hosts SQL Server. 尝试手动启动代理时出现一个对话框,其中显示消息“错误 1069: 由于登录失败,服务未启动。”When you attempt to manually start the agent, you see a dialog box that displays the message, "Error 1069: The service did not start due to a logon failure."

数据同步错误 1069 对话框

  • 原因Cause. 出现此错误可能的原因是,自从创建代理和代理密码后,本地服务器上的密码已更改。A likely cause of this error is that the password on the local server has changed since you created the agent and agent password.

  • 解决方法Resolution. 将代理的密码更新为当前服务器密码:Update the agent's password to your current server password:

    1. 找到 SQL 数据同步客户端代理服务。Locate the SQL Data Sync client agent service.
      a.a. 选择“开始”。Select Start.
      b.b. 在搜索框中输入 services.mscIn the search box, enter services.msc.
      c.c. 在搜索结果中,选择“服务”。In the search results, select Services.
      d.d. 在“服务”窗口中,滚动到 SQL Data Sync Agent 所对应的条目。In the Services window, scroll to the entry for SQL Data Sync Agent.
    2. 右键单击“SQL Data Sync Agent”并选择“停止”。 Right-click SQL Data Sync Agent, and then select Stop.
    3. 右键单击“SQL Data Sync Agent”并选择“属性”。 Right-click SQL Data Sync Agent, and then select Properties.
    4. 在“SQL Data Sync Agent 属性”中,选择“登录”选项卡。 On SQL Data Sync Agent Properties, select the Log in tab.
    5. 在“密码”框中输入自己的密码。In the Password box, enter your password.
    6. 在“确认密码”框中再次输入自己的密码。In the Confirm Password box, reenter your password.
    7. 依次选择“应用”、“确定” 。Select Apply, and then select OK.
    8. 在“服务”窗口中,右键单击“SQL Data Sync Agent”服务并单击“启动”。 In the Services window, right-click the SQL Data Sync Agent service, and then click Start.
    9. 关闭“服务”窗口。Close the Services window.

无法提交代理密钥I can't submit the agent key

创建或重新创建代理密钥后,尝试通过 SqlAzureDataSyncAgent 应用程序提交该密钥时,After you create or re-create a key for an agent, you try to submit the key through the SqlAzureDataSyncAgent application. 提交过程无法完成。The submission fails to complete.

同步错误对话框 - 无法提交代理密钥

  • 先决条件Prerequisites. 在继续之前,请先检查是否符合以下先决条件:Before you proceed, check the following prerequisites:

    • SQL 数据同步 Windows 服务正在运行。The SQL Data Sync Windows service is running.

    • SQL 数据同步 Windows 服务的服务帐户具有网络访问权限。The service account for SQL Data Sync Windows service has network access.

    • 出站 1433 端口在本地防火墙规则中处于打开状态。The outbound 1433 port is open in your local firewall rule.

    • 本地 IP 已添加到同步元数据库的服务器或数据库防火墙规则。The local ip is added to the server or database firewall rule for the sync metadata database.

  • 原因Cause. 代理密钥唯一标识每个本地代理。The agent key uniquely identifies each local agent. 密钥必须满足以下两个条件:The key must meet two conditions:

    • SQL 数据同步服务器和本地计算机上的客户端代理密钥必须相同。The client agent key on the SQL Data Sync server and the local computer must be identical.
    • 客户端代理密钥仅能使用一次。The client agent key can be used only once.
  • 解决方法Resolution. 如果代理无法正常运行,是因为不满足其中一个条件或这两个条件都不满足。If your agent isn't working, it's because one or both of these conditions are not met. 若要使代理再次运行:To get your agent to work again:

    1. 生成一个新密钥。Generate a new key.
    2. 向代理应用新密钥。Apply the new key to the agent.

    向代理应用新密钥:To apply the new key to the agent:

    1. 在文件资源管理器中,转到代理安装目录。In File Explorer, go to your agent installation directory. 默认安装目录为 C:\Program Files (x86)\Microsoft SQL Data Sync。The default installation directory is C:\Program Files (x86)\Microsoft SQL Data Sync.
    2. 双击“bin”子目录。Double-click the bin subdirectory.
    3. 打开 SqlAzureDataSyncAgent 应用程序。Open the SqlAzureDataSyncAgent application.
    4. 选择“提交代理密钥”。Select Submit Agent Key.
    5. 在提供的空白处粘贴剪贴板中的密钥。In the space provided, paste the key from your clipboard.
    6. 选择“确定” 。Select OK.
    7. 关闭程序。Close the program.

如果与客户端代理关联的本地数据库不可访问,则无法从门户删除该客户端代理The client agent can't be deleted from the portal if its associated on-premises database is unreachable

如果注册到 SQL 数据同步客户端代理的本地终结点(即数据库)不可访问,则无法将该客户端代理删除。If a local endpoint (that is, a database) that is registered with a SQL Data Sync client agent becomes unreachable, the client agent can't be deleted.

  • 原因Cause. 无法删除本地代理,因为该代理中仍然注册了不可访问的数据库。The local agent can't be deleted because the unreachable database is still registered with the agent. 尝试删除代理时,删除过程尝试访问数据库,操作失败。When you try to delete the agent, the deletion process tries to reach the database, which fails.

  • 解决方法Resolution. 使用“强制删除”来删除不可访问的数据库。Use "force delete" to delete the unreachable database.

备注

如果在执行“强制删除”后,同步元数据表仍然存在,请使用 deprovisioningutil.exe 将其清除。If sync metadata tables remain after a "force delete", use deprovisioningutil.exe to clean them up.

本地同步代理应用无法连接到本地同步服务Local Sync Agent app can't connect to the local sync service

  • 解决方法Resolution. 请尝试以下步骤:Try the following steps:

    1. 退出应用。Exit the app.
    2. 打开组件服务面板。Open the Component Services Panel.
      a.a. 在任务栏上的搜索框中输入 services.mscIn the search box on the taskbar, enter services.msc.
      b.b. 在搜索结果中,双击“服务”。In the search results, double-click Services.
    3. 停止“SQL 数据同步”服务。Stop the SQL Data Sync service.
    4. 重启“SQL 数据同步”服务。Restart the SQL Data Sync service.
    5. 重新打开应用。Reopen the app.

从命令提示符运行 Data Sync AgentRun the Data Sync Agent from the command prompt

可以从命令提示符运行以下 Data Sync Agent 命令:You can run the following Data Sync Agent commands from the command prompt:

对服务执行 Ping 命令Ping the service

使用情况Usage

SqlDataSyncAgentCommand.exe -action pingsyncservice

示例Example

SqlDataSyncAgentCommand.exe -action "pingsyncservice"

显示已注册的数据库Display registered databases

使用情况Usage

SqlDataSyncAgentCommand.exe -action displayregistereddatabases

示例Example

SqlDataSyncAgentCommand.exe -action "displayregistereddatabases"

提交代理密钥Submit the agent key

使用情况Usage

Usage: SqlDataSyncAgentCommand.exe -action submitagentkey -agentkey [agent key]  -username [user name] -password [password]

示例Example

SqlDataSyncAgentCommand.exe -action submitagentkey -agentkey [agent key generated from portal, PowerShell, or API] -username [user name to sync metadata database] -password [user name to sync metadata database]

注册数据库Register a database

使用情况Usage

SqlDataSyncAgentCommand.exe -action registerdatabase -servername [on-premisesdatabase server name] -databasename [on-premisesdatabase name]  -username [domain\\username] -password [password] -authentication [sql or windows] -encryption [true or false]

示例Examples

SqlDataSyncAgentCommand.exe -action "registerdatabase" -serverName localhost -databaseName testdb -authentication sql -username <user name> -password <password> -encryption true

SqlDataSyncAgentCommand.exe -action "registerdatabase" -serverName localhost -databaseName testdb -authentication windows -encryption true

取消注册数据库Unregister a database

使用此命令取消注册数据库时,它会完全取消数据库的设置。When you use this command to unregister a database, it deprovisions the database completely. 如果数据库参与其他同步组,则此操作会中断其他同步组。If the database participates in other sync groups, this operation breaks the other sync groups.

使用情况Usage

SqlDataSyncAgentCommand.exe -action unregisterdatabase -servername [on-premisesdatabase server name] -databasename [on-premisesdatabase name]

示例Example

SqlDataSyncAgentCommand.exe -action "unregisterdatabase" -serverName localhost -databaseName testdb

更新凭据Update credentials

使用情况Usage

SqlDataSyncAgentCommand.exe -action updatecredential -servername [on-premisesdatabase server name] -databasename [on-premisesdatabase name]  -username [domain\\username] -password [password] -authentication [sql or windows] -encryption [true or false]

示例Examples

SqlDataSyncAgentCommand.exe -action "updatecredential" -serverName localhost -databaseName testdb -authentication sql -username <user name> -password <password> -encryption true

SqlDataSyncAgentCommand.exe -action "updatecredential" -serverName localhost -databaseName testdb -authentication windows -encryption true

后续步骤Next steps

有关 SQL 数据同步的详细信息,请参阅以下文章:For more info about SQL Data Sync, see the following articles: