小树旧系统同步桥：托管方代部署工单

请在现有小树旧站上部署独立、只读的数据同步桥，并按下列条件验收。旧站仍有客户使用，请保留现有网站与数据库业务数据。

目标和已知现场情况

目标地址：https://a018.2018.z01.com/xiaoshu-sync/v1/health。
2026-10-11 23:02（北京时间）实测：同步桥 HTTP 404；新系统返回 configured=false、bridgeReachable=false，所有数据集无同步成功检查点。
旧站首页可访问。需要在服务器端核查实际 IIS 站点、域名绑定、/xiaoshu-sync 子应用及 IIS 日志子状态，确认是否未部署或映射错误。
旧数据库此前核验为 zatu2024，SQL Server 2016 / 13.0.5026.0，服务器名 SZ02；部署时请再次确认，不得误连其他网站数据库。
网站 CMS 管理账号不具备现成 IIS 发布能力，不能用模板编辑或静态站点发布替代本次安装。

交付包

交付压缩包中 bridge/xiaoshu-legacy-sync-bridge-iis.zip 为 Windows x64 自包含发布。请先把它展开到独立安装目录，例如 C:\deploy\xiaoshu-legacy-sync，以下命令均从该目录执行。

桥包 SHA-256：d1e2b65f9c81a5f7e0a2c4855a8bea2380361e11f929ca4111a79efe74cab7b9。

桥包包含 runtime、安装/测试/回滚脚本、SQL 安装及核验脚本、配置模板和 README；不包含正式密钥和连接串。三个部署脚本已与当前源码逐字比对，包内没有 appsettings.Production.json。

部署前需填写的参数

参数	负责方与要求
实际 IIS SiteName	旧站托管方确认绑定 a018.2018.z01.com 的站点名称，不能直接默认 Default Web Site
SQL 连接串	旧站托管方提供具备必要读取权限的专用连接；DDL 安装另用有权限的账号，不在工单回执中回传密码
HMAC KeyId / Secret	部署管理员生成新的 KeyId 与至少 32 位随机 Secret，通过双方约定的安全渠道交给新系统管理员
AllowedIps	新系统管理员提供真实服务器出口 IP；DNS 的入站 IP 或开发电脑 IP 不等于实际出口 IP
独立应用池和目录	建议 XiaoshuLegacySync、C:\inetpub\xiaoshu-sync；不得与旧站根应用共用应用池

缺少其中任何一项时请明确回报缺项，不得用空配置或开放任意来源的方式代替。若当前托管套餐不支持独立 IIS 子应用，请先回报限制及可提供的独立服务/受控反向代理方案，不要只上传文件后宣布完成。

旧站托管方操作

备份 IIS 配置、现有同名同步桥应用（若有）及目标数据库。记录备份路径和时间。确认 IIS 具备 AspNetCoreModuleV2；桥为自包含发布，不要求安装 .NET 8 Runtime，但需要这个 IIS 模块。
将 deployment/appsettings.Production.template.json 复制到 C:\secure\xiaoshu-sync.production.json，安全填写上述参数。PathBase 保持 /xiaoshu-sync；不填占位值，不将配置打包回传。

在管理员 Windows PowerShell 中确认实际站点、域名绑定并预检：

Import-Module WebAdministration
Get-Website | Select-Object Name, State, PhysicalPath
Get-WebBinding | Select-Object ItemXPath, Protocol, BindingInformation
$targetSite = Read-Host '绑定 a018.2018.z01.com 的实际 IIS 站点名称'
.\deployment\Install-XiaoshuLegacySyncBridge.ps1 -PublishPath . -ConfigurationPath C:\secure\xiaoshu-sync.production.json -SiteName $targetSite -HealthUrl https://a018.2018.z01.com/xiaoshu-sync/v1/health -PreflightOnly

预检通过后安装独立应用，先确认外部健康地址能返回本桥服务身份。健康接口本身不依赖 SQL 同步表：

.\deployment\Install-XiaoshuLegacySyncBridge.ps1 -PublishPath . -ConfigurationPath C:\secure\xiaoshu-sync.production.json -SiteName $targetSite -HealthUrl https://a018.2018.z01.com/xiaoshu-sync/v1/health

与新系统管理员确认消费端、凭据和后续部署准备好后，在确认过的旧库执行 database/install.sql，再执行 database/verify-readonly.sql。SQL 脚本是多个 GO 分隔的批次，应使用 SSMS/sqlcmd 的正常脚本执行方式。确认两个日志表、一个失败关闭的命令过程及 12 个变更触发器，WritesFailClosed=1。不要修改业务字段、执行写桥命令、清空变更日志或业务表。

执行真实签名与数据库读取验收；只返回健康 200 不够：

.\deployment\Test-XiaoshuLegacySyncBridge.ps1 -BaseUrl https://a018.2018.z01.com/xiaoshu-sync -ConfigurationPath C:\secure\xiaoshu-sync.production.json

应通过健康身份、签名 manifest、11 个数据集 changes 首页读取。manifest.consistent=false 表示读取期间旧库变化，需稍后重试，不应修改程序强行判定通过。不能用静态 JSON 页面替代服务。

抽查旧站登录、首页和一项只读业务查询仍正常，保留 IIS 站点与应用的实际配置证据。回填部署回执，隐藏所有密码、Secret、令牌与学生业务内容。

验收不通过时

404：回报目标站点、绑定、子应用映射，以及该请求的 IIS sc-status / sc-substatus / sc-win32-status；确认包所在目录已创建为 IIS 应用。
500 或启动失败：检查应用池的 64 位模式、AspNetCoreModuleV2、配置及目录权限，回传脱敏事件记录。
401/403：核查签名配置、双方服务器时间及实际出口 IP 白名单，不关闭认证。
SQL 查询失败：核查目标数据库、对象安装、连接权限和实际错误；不以健康接口成功关闭工单。
安装脚本会输出原桥备份路径；已有桥需要回滚时执行包内 Rollback 脚本并显式填写 HealthUrl。首次安装没有旧桥备份，须由托管方恢复安装前 IIS 配置或仅移除新建子应用，禁止删除旧站目录。

新系统侧后续工作（由新系统管理员负责）

旧站托管方完成桥部署不等于夜间同步完成。新系统还需安全配置 XIAOSHU_LEGACY_SYNC_BASE_URL、KEY_ID、SECRET；验收全数据集“保留新系统修改、记录冲突”和主附表原子性；完成一次真实同步及业务 ID/校验和对账，保留 684 条待核对冲突；最后安装并验收每天 Asia/Shanghai 23:00 的服务器任务。不得通过手工修改 checkpoint 或将全部冲突标记解决来通过验收。

当前聊天的 23 点自动任务会记录阻塞并检查后续部署结果；它不替代服务器端作业。请按职责分工回传旧桥部署和新系统接入各自的验收结果。

hosting-bridge-deployment-request.md 6.5 KB Permalink Histórico Raw