授权终端部署指南

WINDOWS SERVICE

Windows Service 部署指南

适用于现有 HitekAuthClientServiceSetup.exe 安装器及 Windows 服务交付包。请使用同一批次的安装器、升级组件和客户端，不要从开发输出目录拼装文件。

1. 准备安装资料

1. 使用具有本机管理员权限的账户登录 Windows。请负责人准备与服务器及正式交付包匹配的 .NET Framework 运行环境，按随包 exe.config 和发布说明核对；不能用 .NET 8 代替。
2. 把安装器压缩包完整解压到长期保留的目录，例如 D:\HitekAuthClient。不要在 ZIP 内直接运行，不要安装到临时下载目录。
3. 负责人核对安装器的 HitekAuthClientServiceSetup.exe.config 中 RootURL 以及客户端授权中心设置。安装器会连接授权中心获取当前 Windows 服务包；仅有 Setup 文件不能完成离线安装。
4. 如已有服务，先打开 services.msc（Win+R 输入后回车），查找“海特授权服务终端”，记录服务可执行文件路径、登录账户及启动类型。不要在另一目录重复安装。

2. 填写并保存配置

1. 右键 HitekAuthClientServiceSetup.exe，选择“以管理员身份运行”。
2. 在“服务器名称”填写负责人指定的名称，它对应 ClientName。不要随意更名或复用另一台机器的名称。
3. 点击“新增连接”，填写连接名称，明确选择“SQL Server”或“MySQL”。在“完整连接字符串”中粘贴负责人提供的内容；有多条连接时逐条录入。
4. 需要向导时打开“生成向导”，填写数据库地址、端口、库名和身份验证方式，点击“生成并填入字符串”，再检查最终字符串。只修改向导字段不会自动应用。
5. 点击“保存全部配置”。未安装时只保存本地缓存；已经安装时会卸载、重装服务并应用配置，造成短暂停服并重新触发业务处理，须安排维护时间。

配置缓存为安装器目录下的 HitekAuthClientConfig.Json。安装及升级将连接名称、类型和完整字符串写入服务目录内的 HitekAuthClientService.exe.config 与 HitekAuthClientApplication.exe.config。后续通过 Setup 保存，避免只改服务配置而没有更新缓存。

3. 安装与首次验收

1. 再次确认数据库备份和停旧客户端已完成，然后点击“立即安装”，等待窗口日志完成下载、解压、写入配置与安装。
2. 点击“打开服务目录”。默认位于安装器目录下的 HitekAuthClientService 子目录；不要在安装后移动或删除父目录中的 Setup。
3. 打开 services.msc，检查下面两个服务均存在、正在运行且启动类型为“自动”。也可以按下一节的查询命令核对。
4. 检查本次时间的程序日志、授权管理端终端状态，以及目标业务系统的授权结果。服务显示“正在运行”只能证明服务启动，不能替代业务验收。

4. 启停与日志

开始菜单搜索“PowerShell”，右键“以管理员身份运行”。先查询服务和实际路径：

Get-Service -Name HitekAuthClientService,HitekAuthClientServiceDeamons
sc.exe qc HitekAuthClientService
sc.exe qc HitekAuthClientServiceDeamons

停止：先守护服务，再主服务

Stop-Service -Name HitekAuthClientServiceDeamons
Stop-Service -Name HitekAuthClientService
Get-Service -Name HitekAuthClientService,HitekAuthClientServiceDeamons

确认两项都是 Stopped。如果服务不存在或停止失败，先交给负责人核对，不要继续覆盖文件。

主服务启动的业务程序和更新程序是独立进程，停服务后还需检查：

Get-Process -Name HitekAuthClientApplication,HitekAuthClientServiceSetup,HitekAuthClientServiceSetupUpdateConsole -ErrorAction SilentlyContinue

关闭自己打开的 Setup 窗口，等待后台任务自然退出。若仍有进程，由负责人判断后处理；不要直接强杀正在写库的进程。需要跨重启维护时，请负责人同时管理两项服务的启动类型，结束后恢复原设置。

启动：先主服务，再守护服务

Start-Service -Name HitekAuthClientService
Start-Service -Name HitekAuthClientServiceDeamons
Get-Service -Name HitekAuthClientService,HitekAuthClientServiceDeamons

查看日志

在 Setup 点击“打开服务目录”，查看 Logs 中当天的 AT_yyyyMMdd.log 和 ERROR_yyyyMMdd.log；安装器自身日志在其所在目录的 Logs。滚动日志可能带附加序号，具体位置以随包 log4net.config / log4netDeamons.config 为准。启动失败且未产生日志时，打开“事件查看器 → Windows 日志 → 应用程序 / 系统”。

5. 升级与人工回退

升级前和升级后

1. 安排维护窗口，先停两项服务并确认后台进程退出，再将整个安装器目录复制到另一个备份目录，保留 Setup、配置缓存、服务程序、业务文件及日志，同时备份业务数据库。
2. 负责人确认授权中心发布的是目标 Windows 版本；更新 Setup 时须使用匹配的 HitekAuthClientServiceSetup.exe、HitekAuthClientUpdate.dll、HitekAuthClientServiceSetupUpdateConsole.exe 等正式文件，保留本机 JSON 缓存，不带入打包机器的配置。
3. 以管理员身份运行 Setup，核对名称和连接后点击“立即安装”。只有负责人明确要求重新覆盖安装时才使用“强制重新安装”。检查窗口日志、服务状态和业务授权结果。

主服务启动及定时任务会调用父目录 Setup 的 backupdate 检查远端版本。当前 Windows 流程按授权中心版本下载更新，不使用 Linux 的 updates/inbox、镜像或 .ready 文件。

升级失败时如何回退

1. 先按上一节停止守护和主服务，确认业务与升级进程退出。保留失败现场和日志，不要删除当前目录。
2. 由负责人确认旧程序与当前配置、业务数据兼容，并已处理更新源。若有可用的已批准旧包，可通过 Setup 重新安装；若采用完整目录备份恢复，按下面步骤在原路径恢复。
3. 在原服务目录，以管理员身份打开命令提示符（cmd），执行随包 unstall.bat，确认两项目标服务已卸载。记录其他报错交负责人判断；脚本中的旧 vshost 项不一定存在。
4. 保留当前目录副本后，把确认可用的完整备份恢复到原安装路径，保留负责人确认的本机配置与业务状态；不要仅混拷某一个 DLL，也不要盲目覆盖升级后已产生的数据。
5. 在恢复后的服务目录，以管理员 cmd 执行 install.bat。脚本会注册、启动两项服务并设为自动。重新完成服务、日志、业务结果验收。

回退程序不能撤销已写入业务数据库的变更。没有备份、服务无法卸载或数据兼容性不明时，应停在故障现场，由负责人处理。

6. Windows 常见故障

LINUX DOCKER · 3.1.1

Linux Docker 部署指南

适用：已安装 Docker Engine 和 Docker Compose 插件的 Linux 服务器。Ubuntu 22.04/24.04 为当前部署目标；麒麟、鲲鹏服务器需要匹配的 Docker、Linux 内核及 CPU 架构，并完成现场验收。镜像内已包含 .NET 8 和程序依赖，服务器不用另装 .NET，也不用连接互联网。

Windows 继续使用现有 Windows Service 安装和升级流程。

一、先准备文件和资料

管理员把 Docker 交付 ZIP 解压后上传到统一下载空间，保持目录结构。部署人员也可以在办公电脑解压 ZIP，用文件传输工具或 U 盘把需要的文件放到服务器用户的 ~/hitek-docker/ 目录。

在服务器终端逐条执行：

uname -m
sudo docker version
sudo docker compose version

x86_64 选择 amd64；aarch64/arm64（例如鲲鹏）选择 arm64。以下命令以 amd64 为例，ARM64 服务器把命令中的 amd64 替换为 arm64。如果 Docker 命令报错，请先让管理员处理，再继续。

文件应按以下结构放置（只需一个架构的镜像）：

~/hitek-docker/
  hitek-auth-client-3.1.1-linux-amd64.tar
  hitek-auth-client-3.1.1-linux-amd64.tar.sha256
  hitek-auth-client-3.1.1-linux-amd64.ready
  docker-deployment/
    docker-install.sh
    docker-compose.yml
    .env.example
    appsettings.template.json
    manage.sh
    upgrade.sh
    auto-upgrade.sh
    enable-auto-upgrade.sh

.env.example 是以点开头的文件，文件传输工具可能默认隐藏它，也必须复制。负责人还需安全提供授权中心地址、客户端名称、业务库连接信息和生产配置文件，并备份业务数据库、安排停止旧客户端。真实密码和配置不要上传公共下载空间。

二、校验、导入和安装

以下以 3.1.1 / amd64 为例；其他版本须同时替换文件名及镜像标签，ARM64 须将 amd64 换成 arm64。安装脚本自动按 CPU 选择架构；若交付版本不同，请负责人核对安装目录 .env 的 HITEK_AUTH_CLIENT_IMAGE 与导入镜像标签一致。

先核对镜像完整性，必须看到 OK 后才导入：

cd ~/hitek-docker
sha256sum -c hitek-auth-client-3.1.1-linux-amd64.tar.sha256
sudo docker load --input hitek-auth-client-3.1.1-linux-amd64.tar
sudo bash docker-deployment/docker-install.sh /opt/hitek-auth-client

首次安装只接受不存在的目标目录。提示“目标已存在”时请停止，由负责人确认是否为已有客户端；已有 Docker 部署用后面的升级流程。

安装后以下文件和目录在服务器上长期保留：

升级只更换程序镜像，配置、数据、缓存和日志目录持续挂载。Docker 镜像内有共享 .NET 运行时，不需要单文件解压；cache 供运行临时文件使用。

三、填写配置

建议由负责人给出填好的 appsettings.json，部署人员直接复制：

sudo cp ~/hitek-docker/appsettings.json /opt/hitek-auth-client/config/appsettings.json
sudo chown root:1654 /opt/hitek-auth-client/config/appsettings.json
sudo chmod 640 /opt/hitek-auth-client/config/appsettings.json

完整配置须保留模板外层 HitekAuthClient，请负责人核对 ServerRoot、ServerGetApi 和 ServerDriverApi 等授权中心地址。下面 Customers 只是配置片段，不能替换整个 JSON 文件。

也可执行 sudo nano /opt/hitek-auth-client/config/appsettings.json 编辑。修改后按 Ctrl+O、回车保存，Ctrl+X 退出。必须填写真实 ClientName，将 ApplyAuthorizationPackages 改为 true，并填写 Customers 或 Databases；原始空模板会被拒绝启动。

以下是 Customers 的 ILIS Java/MySQL 格式示例，负责人需把全部示例值换成现场值。其他系统不能直接沿用此示例中的 SystemType：

"Customers": [
  {
    "CustomerName": "实际单位授权名称",
    "SystemType": "ILIS_JAVA",
    "DatabaseType": "MYSQL",
    "DatabaseName": "实际库名",
    "ConnectionString": "Server=数据库IP;Port=3306;Database=实际库名;User ID=数据库用户;Password=实际密码;"
  }
]

数据库和授权中心需在服务器所在内网可达。容器中的 localhost 或 127.0.0.1 指容器自身；连接服务器上的数据库请填写可达的宿主机 IP。密码中的引号、反斜杠须按 JSON 规则转义；不熟悉格式时请负责人准备配置。

四、检查、首次同步，再启动后台服务

先只做配置和环境检查，不进行业务同步：

cd /opt/hitek-auth-client
sudo bash manage.sh check
sudo bash manage.sh connections

check 验证配置、运行时、字符编码、授权加密和目录读写；connections 验证 DNS/TCP/TLS 和数据库登录、SELECT 1，不写业务表。失败时不要继续，把错误及 logs/ 下检测报告交给负责人。

负责人确认数据库备份完成且旧客户端已停止后，执行一次同步。此时不要启动后台容器：

sudo bash manage.sh once
sudo tail -n 100 /opt/hitek-auth-client/logs/hitek-auth-client.log

确认本次命令成功、业务系统授权生效后，再启动持续运行：

sudo bash manage.sh start
sudo bash manage.sh status
sudo bash manage.sh logs

状态应为 Up，稍等后显示 healthy。healthy 表示容器中的程序进程正常，不代表授权中心、数据库或业务同步成功，仍需查看日志和业务结果。若提示已有同步实例运行，先执行 sudo bash manage.sh stop，再做单次同步。

五、开启“放入目录后自动升级”

完成首次验收后，在安装目录执行一次：

cd /opt/hitek-auth-client
sudo bash enable-auto-upgrade.sh
sudo systemctl list-timers 'hitek-auth-client-update-*' --all

监视器由宿主机 systemd 运行，每分钟检查 updates/inbox/。应用容器不需要控制 Docker；管理员操作升级目录即可。

以后拿到新版本时，先把该 CPU 架构的 .tar、同名 .tar.sha256、.ready 三个文件完整传到临时目录。以下以当前 3.1.1 的文件名演示，实际升级时换成新版本的文件名：

cd ~/hitek-docker
sha256sum -c hitek-auth-client-3.1.1-linux-amd64.tar.sha256
sudo cp hitek-auth-client-3.1.1-linux-amd64.tar /opt/hitek-auth-client/updates/inbox/
sudo cp hitek-auth-client-3.1.1-linux-amd64.tar.sha256 /opt/hitek-auth-client/updates/inbox/
sudo cp hitek-auth-client-3.1.1-linux-amd64.ready /opt/hitek-auth-client/updates/inbox/

必须最后复制 .ready，它是开始处理的信号；不要把 ZIP、两个架构或未传完的归档一起投放进去。.ready 由发布工具生成，不需要部署人员手工填写。

服务器自动校验完整性、包类型和 CPU，检查新版本配置及本机环境，停止旧容器并备份数据，然后启动新镜像、等待健康检查。部署期间短暂停止同步；检查失败或启动失败会记录原因，启动失败时尝试自动恢复原镜像 ID；Docker 本身异常时可能回退失败，必须查看结果确认。检测到正有其他部署操作时会等待下次，不会并发升级。

处理后的三件文件及 result.log 放进 updates/applied/时间记录/ 或 updates/failed/时间记录/。同一个包失败后不会无限重试；先处理原因，再由管理员重新投放。查看结果：

sudo find /opt/hitek-auth-client/updates/applied /opt/hitek-auth-client/updates/failed -name result.log

用 sudo cat 上一步显示的完整路径 查看日志。启用脚本也会显示对应 journalctl 查看命令。停止自动检查可用 sudo systemctl disable --now 实际定时器名称.timer（名称见 list-timers 输出）。

六、手动升级与回退

升级和 --local 回退都要求当前已有正在运行的容器。若容器已经停止或自动回退失败，先由负责人排查 Docker 并恢复运行状态，不要反复运行升级脚本。

需要立即处理升级包时，可在安装目录直接执行：

cd /opt/hitek-auth-client
sudo bash upgrade.sh ~/hitek-docker/hitek-auth-client-3.1.1-linux-amd64.tar hitek-auth-client:3.1.1-linux-amd64

升级前保留 .env、Compose、config 以及停止写入后的 data 备份；cache 和 logs 持续保留，不重复打进数据备份。.env 最终写入固定镜像 ID，同名版本标签变化不影响失败回退。请保留原镜像，验收完成前不要执行 docker image prune -a。

需要人工回退时，负责人打开对应 backups/upgrade-时间/old-image-id.txt，复制其中的镜像 ID（以 sha256: 开头），再执行：

sudo bash upgrade.sh --local sha256:实际旧镜像ID

自动回退只恢复程序镜像，保留当前配置和数据；不会倒灌旧数据，以免重复处理授权业务。已写入业务数据库的变更不能仅靠回退镜像撤销。未来版本若有不兼容的数据格式变化，必须另附迁移方案，不应直接投入自动升级目录。

七、运行维护和验收范围

cd /opt/hitek-auth-client
sudo bash manage.sh stop
sudo bash manage.sh start
sudo bash manage.sh status
sudo bash manage.sh logs

Docker 负责异常退出后的重启。要随服务器启动，Docker 服务本身须开机启动，容器不可处于管理员手动停止状态。程序默认用 UID/GID 1654 运行；config 只读挂载，data/cache/logs 由该用户写入。日志会滚动保存，备份和升级归档由管理员定期清理。

交付文档记录了 amd64 容器和 ARM64 模拟环境测试，这些记录不代表当前服务器已验收。Docker 容器里的发行版是镜像的 Debian 12，与宿主机的 Ubuntu/麒麟不同；这不意味着已经验证所有麒麟版本。鲲鹏实机、现场数据库业务、宿主机 systemd 定时器和整机重启行为仍需现场验收。

八、Linux Docker 常见故障