集团服务集群部署

集群部署概述

集团服务采用主从集群架构，由1个主节点（leader服务）和多个从节点（slave服务）组成。

• 从节点（slave服务）：通过心跳定期向主节点同步自身状态与用户数。
• 主节点（leader服务）：负责集群协调管理、用户数汇总，并将汇总结果同步至所有从节点。

集群部署的核心优势：

• 提升并发处理能力：通过增加服务器节点与负载均衡技术，显著提升集团服务在高并发访问下的处理能力。
• 增强系统稳定性：实现服务的高可用性，当部分节点故障时，可保障服务不中断或快速恢复。
• 提高可扩展性：支持服务器节点动态扩展，灵活应对用户量与并发量的持续增长需求。

使用须知

• 集群部署需要3台及以上服务器，且所有服务器必须是同一操作系统。
• 集团服务和集团扩展模块需为13.1.0及以上版本。
• 比特授权云平台上的集团授权码已勾选“冗余检查”；不支持时请联系比特安索开通。

部署模式选择

根据性能需求、配置复杂度容忍度，选择以下两种部署模式之一：

客户端直连模式

• 连接方式：客户端直接通过IP地址和端口号与集群内特定服务实例建立连接。
• 适用场景：对性能要求极高，且能接受配置复杂度的场景。

代理服务器连接模式

• 连接方式：客户端通过代理服务器与集群内特定服务实例进行交互，代理服务器作为中介，负责接收客户端请求并按策略转发至集群内一个或多个服务实例。
• 适用场景：对可扩展性、配置简化要求较高，且能接受轻微延迟的场景。

模式对比

集群部署操作指导

下面以三台服务器为例，介绍集群部署的方法。

注意：授权码不支持跨操作系统激活，集群内所有服务器需为同一操作系统。

前提条件：开启授权码集群支持

1. 开发商登录比特授权云平台，在授权码的“授权信息”页签勾选“冗余检查”，启用集群功能；设置“终端限制”，设置数应与实际部署的集群服务器数量保持一致。（本示例设为3）
2. 最终用户已从开发商处获取了支持集群功能的授权码。

激活授权

集群授权激活分为“在线激活”与“离线激活”两种方式，最终用户可根据网络环境选择。

方式一：在线激活

1. 添加支持集群功能的授权码

最终用户登录集群内任意一台集团授权服务器，在“授权列表”页点击“添加授权码”。对集群内所有服务器执行相同操作，添加完成后，授权码状态均显示为“等待服务器接入”。

2. 配置集群网络

登录任意一台集团授权服务器，在“授权列表”页点击“设置”按钮，输入集群内所有服务器的IP，格式为ip:port。

设置完成后，三台服务器将自动建立连通，此时授权码状态均显示为“正常”可用状态。

说明：默认管理端口为8274，使用默认端口配置集群地址时可以省略端口号，直接配置IP。

3. 验证集群联通状态

授权码后方的小电脑图标数量对应集群服务器总数（本示例显示3个），鼠标悬浮至图标，可查看对应服务器的IP地址与运行状态，首个图标默认对应本机。

运行要求：集群内在线服务数量需大于部署服务总数的1/2（本示例需至少2台在线），否则授权不可用。

方式二：离线激活

1. 获取集群服务器设备信息

最终用户提供集群内所有服务器的设备码或MAC地址。以MAC地址为例，3台服务器的MAC地址如下：

• 机器A：E0-D0-45-82-8D-B3
• 机器B：E0-D0-45-82-8D-B7
• 机器C：00-50-56-C0-00-08

2. 开发商为授权码绑定设备并生成授权文件

开发商登录比特授权云平台，在授权码的“设备管理”页签点击“添加设备”，输入第一步获取到的3个MAC地址并完成设备绑定。

依次点击各设备后方的“激活”按钮，生成3个独立的license.upd授权文件，并发送给最终用户。

注意：每个license.upd文件与对应MAC地址绑定，仅限指定服务器使用。

3. 最终用户导入授权文件

最终用户将license.upd文件分别拷贝至对应MAC地址的服务器。

登录集团授权管理中心，在“授权列表”点击右上角“导入授权文件”，选择对应license.upd文件，点击“激活/升级/返还”完成授权导入。

说明：Linux集团服务支持通过命令行导入license.upd授权文件，参见集团服务授权管理命令。

4. 配置集群网络

操作与在线激活的“配置集群网络”一致。

5. 验证集群联通状态

操作与在线激活的“验证集群联通状态”一致。

客户端连接集群内的集团服务

客户端连接集群支持客户端直连和代理服务器连接两种模式，最终用户可根据自身场景需求选择使用。

客户端直连

需预先获取集群内所有集团服务节点的IP地址和端口信息，并为不同的客户端分配独立IP，这里也可以使用客户端轮询方案，轮询方案具体操作过程请见《比特安索客户端轮询方案》文档。

代理服务器连接

在代理转发过程中，为了提高系统的可用性和性能，通常会引入负载均衡机制。负载均衡器会根据一定的算法（如轮询、最少连接数等）将请求分发给集群服务器中的不同节点。此外，当某个节点出现故障时，负载均衡器会将请求自动转发到其他可用的节点上，从而实现故障转移。

集团服务集群部署推荐使用Nginx作为反向代理与负载均衡工具，Nginx配置示例如下：

注意：为保证同一客户端的请求始终送至同一台服务器，必须使用ip_hash实现粘性IP。

http {
    upstream test {
        ip_hash;
        server 192.168.1.105:8273;
        server 192.168.1.79:8273;
        server 192.168.1.92:8273;
        server 192.168.1.12:8273;
        server 192.168.1.62:8273;
    }

    server {
        listen      8123;

        location / {
            proxy_pass  http://test;
        }
    }
}

注意：

• 集团集群之间用户数定6s同步一次，整个集群的可接入数量由license控制。
• 由于集群内的用户数同步需要时间，会造成授权点数的占用大于最多可用数。
• 如果想看所有登录集团服务的用户，需要在不同的服务器查看。
• “客户端直连”与“代理服务器连接”为两种客户端连接集群内集团服务的方案，最终用户根据自身场景需求选择其一即可。

集群运维

添加新服务到集群

下面仅介绍离线方式添加新服务的操作流程请参见集群部署操作指导。

1. 获取设备码

最终用户在需要加入集群的新机器上部署集团服务，并将机器的设备码发送给开发商。

2. 开发商修改授权码的属性

开发商登录比特授权云平台，在授权码的“授权信息”页签修改“终端限制”的机器数，修改后的数量应与实际部署的集群服务器个数一致。

3. 为授权码添加新部署集团服务的机器

开发商登录比特授权云平台，在授权码的“设备管理”页签点击“添加设备”输入获取到的设备码，点击“确定”。

4. 产生离线升级文件

点击新添加的设备后面的激活按钮，产生license.upd文件，将产生的license.upd文件发送给最终用户。

5. 最终用户将license.upd文件在新机器的集团服务上激活

6. 将新部署的集团服务加入集群

方法一：打开新部署的集团服务的授权管理中心，将任意一台已经在集群内的机器的IP和端口设置到集群地址内，下一次心跳集团服务间会同步状态，将新服务加入集群。

方法二：打开任意一台集群内的集团服务的授权管理中心，将新加入集群的机器的IP和端口设置到集群地址内，下一次心跳集团服务间会同步状态，将新服务加入集群。

删除集群内的指定服务

打开任意一台集群内的集团服务的授权管理中心，将需要踢出集群的服务的IP和端口在集群地址内删除。如下图：如果想踢出192.168.1.180这台机器，在集群地址设置中，将该IP和port删除，点击“确定”即可，下一次心跳集团服务间会同步状态，将指定服务器踢出集群。

升级集群内的服务

集团服务升级操作参见“安装集团服务”内容说明。

注意：为保证授权不终止，同时升级的集团服务数量必须小于全部集群总数的1/2，否则授权不可用。

升级支持集群的授权码

授权码（SN）升级操作参见“激活集团授权”内容说明。

注意：修改授权有效期、授权可用点数等时，需对集群内所有机器上激活的SN同时升级；仅升级单台服务器的授权，升级内容仅在当前服务器生效。

常见问题与解决方案

集群内的服务器无法正常联通（授权码为不可用状态）

可能原因：集群内机器的网络或者8273端口无法互通。

解决方案：集群内部的机器使用ping ip命令检查网络是否联通，如果网络通畅，则使用curl ip:port命令，检查端口是否允许访问，如果报错则需要检查网络或者防火墙状态。

客户端连接集团服务报错2615

可能原因：

• 服务正在冗余切换；
• 服务状态为wait，客户端连接到了服务，但是服务总数不满足1/2台。

解决方案：查看服务状态，是否有服务宕机，如服务宕机数超过总数的1/2，则需重新启动宕机的服务。

激活授权报错1795

可能原因：授权码不支持冗余属性。

解决方案：联系开发商，给授权码设置冗余属性，并将终端限制数设为需激活的机器数。

feature功能点的激活数大于可用数

可能原因：集群内每6秒同步一次用户数，实际用户数可能高于可用数。

解决方案：目前设计如此，无需额外操作。

需增加服务器的场景

当集群内的所有服务器长时间满负荷运转，且客户端大批量出现264错误时，说明现有集团服务已经无法及时处理客户端请求，需要部署新的集团服务，对集群进行扩容。

集群内部实现原理

名词解释

• Leader服务：是集群中通过选举产生的领导者服务，slave服务定期连接leader服务同步自身状态，并从leader服务获取当前用户数。
• Election消息：发生在集群选举阶段，由其中一台服务器向其他服务器发送选举消息。
• Alive消息：发生在集群选举阶段，检查自身的index和接收到的index大小，如果大于，就返回Alive消息。
• Ignore消息：发生在集群选举阶段，检查自身的index和接收到的index大小，如果小于，就返回Ignore消息。
• Victory消息：发生在集群选举阶段，选举成功后leader将发送Victor消息。

集群内集团服务通信机制

配置第三方数据库

14.2.1及以上版本的集团服务支持配置第三方数据库（目前仅支持MySQL）。开发商可以给多个集团服务指定同一个数据库，其中任何一个集团服务都可以读取到全部日志。

功能特性

配置MySQL数据库后，需重点理解集团服务的数据处理逻辑和规则，避免数据查询异常。

1. 多服务数据共享与聚合：当多个集团服务共用一个MySQL数据库时，RESTful接口返回的是数据库内当前产品下的所有Log信息（而非单服务器数据），实现跨服务器数据统一查询。

支持跨服务查询的RESTful接口清单：log、statistics、errors、borrowclient、featuresV3。

2. 产品数据区分规则：同一集团服务的不同产品，在MySQL数据库中通过表名区分。
3. logoutTime填充：RESTful的statistics接口返回数据包含logoutTime字段，该字段由集团服务后台逐条填充，在多个集团服务共用一个数据库时，会自动选择其中一个服务作为主服务，对logoutTime进行维护，当其中任何一个服务器异常退出后，如果未在5分钟内重新启动，则该服务器的logoutTime会被填充为该服务的退出时间。
4. 跨服务数据查询能力：多个集团服务共用一个MySQL数据库时，即使某一台集团服务退出，仍可通过其他运行的集团服务查询该退出服务的历史数据，不影响数据访问。
5. 多服务特征项和峰值信息查询能力：RESTful新增featuresV3接口，在接入MySQL数据库后，支持查询多个集团服务的特征项信息和峰值信息。

使用须知

• 集团服务版本要求：14.2.1及以上版本支持该功能。
• MySQL版本要求：使用安全、稳定、可靠的版本，建议使用5.7及以上版本。
• 数据兼容性：MySQL不兼容旧版本集团服务的SQLite数据，升级到MySQL后，原SQLite中的旧数据会全部丢失，升级前必须手动备份旧数据，避免数据丢失。
• MySQL数据库权限要求：需要为数据库配置SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、DROP、INDEX权限，且缺一不可。
• MySQL数据库用户认证插件限制：仅支持mysql_native_password认证插件，可使用以下SQL语句创建数据库用户：

CREATE USER 'user'@'%'
IDENTIFIED WITH mysql_native_password
BY '123456';

操作指导

下面以Linux集团服务为例，介绍配置方法：

1. 备份历史数据

因MySQL不兼容旧版本集团服务的SQLite数据，升级到MySQL前需手动备份原SQLite中的旧数据，防止数据丢失。

2. 设置服务编号（serviceIndex）

• 配置MySQL数据库前，必须先设置集团服务的服务编号。多个集团服务共用一个MySQL数据库时，每台服务器的serviceIndex必须唯一，否则会导致服务识别混乱；单服务使用MySQL也需要配置serviceIndex。
• 操作命令，输入“./bit_service -serviceIndex <0-255>”（取值范围为0-255，默认值为0），设置当前服务器的唯一编号。 具体参见集团服务-serviceIndex命令

./bit_service -serviceIndex 3  # 设置服务编号为3

注意：多台服务器的serviceIndex必须互不相同，否则会导致服务识别混乱。

3. 启用MySQL数据库

• 必须先设置有效的serviceIndex，再配置dataPath，否则会报错。
• 操作命令，输入“./bit_service -dataPath db:mysql”，db:mysql为固定值，不可修改。 具体参见集团服务-dataPath命令

./bit_service -dataPath db:mysql  # 启用MySQL数据库

4. 配置MySQL插件

需提前获取比特安索提供的MySQL数据库插件，具体配置方法参见配置MySQL插件。

5. 重启集团服务

完成上述配置后，需要重启服务使配置生效。

6. 验证配置情况（可选）

输入命令“./bit_service -s”，可验证MySQL数据库配置的生效情况。若配置生效，命令行返回结果中会显示MySQL相关连接状态。

配置MySQL插件

配置MySQL插件

1. 下载插件

开发商登录比特授权云平台，在平台左侧“模块下载 > 集团授权模块”中，下载对应操作系统的集团服务MySQL插件（区分Windows和Linux版本，与产品不绑定）。

下载后将获得plugin_mysql.zip压缩包，内含：

• 动态链接库：plugin_mysql.dll（Windows）或plugin_mysql.so（Linux）
• 配置文件：plugin_mysql.ini

2. 部署插件

将压缩包中解压出的动态链接库文件（plugin_mysql.dll或plugin_mysql.so）和配置文件（plugin_mysql.ini），复制到集团服务安装目录下的plugin文件夹中。

3. 配置数据库连接

根据实际的MySQL服务器配置，修改plugin_mysql.ini文件中的参数。支持以下两种配置方式：

• 命令行自动设置（推荐）

此方式通过命令行动态配置，便捷高效。它支持以密文或明文形式存储数据库密码，安全性更高。使用此功能需满足：集团服务版本 ≥ 14.4.0，且MySQL插件版本 ≥ 1.1.0.0。具体操作请参见 -plugin_mysql 及 -appkey 命令的帮助文档。

-plugin_mysql：通过此命令直接设置MySQL数据库连接信息（如主机、数据库名、用户名、密码等），插件将自动完成配置。

-appkey：此命令用于设置加密主密钥。当您在-plugin_mysql中提供的数据库密码为密文时，必须使用此密钥进行解密。若未设置，插件在首次配置时将自动生成一个安全的密钥，确保密文密码的安全存储与使用。

• 配置文件手动设置

此方式通过编辑传统的INI文件进行配置。请注意，在此方式下，数据库密码仅能以明文形式存储。其版本要求为：集团服务版本 ≥ 14.2.1，且MySQL插件版本 ≥ 1.0.0.0。详细的配置规则请参阅下方的“配置文件说明”部分。

4. 生效配置

重启集团服务，使插件配置生效。

说明：集团服务启动阶段会执行MySQL配置校验，开发商可根据校验提示处理异常问题。

配置文件说明：

plugin_mysql.ini为MySQL插件的配置文件，内容及说明如下：

; 此配置文件由bitanswer提供
; 包含连接数据库所需的关键配置信息

; 数据库配置区域，包含连接MySQL数据库所需的各项参数
[Database]

; MySQL服务器的IP地址，本地服务器通常使用127.0.0.1，远程服务器需填写实际IP
ip=127.0.0.1

; MySQL服务器的端口，默认端口为3306，若服务器修改过端口需填写对应值
port=3306

; MySQL数据库的名称，连接时要访问的具体数据库名
database=bitanswer

; 连接数据库的超时时间，单位秒，超过该时间未建立连接则视为连接失败
timeout=30

; 连接数据库的用户名，用于身份验证的数据库账号
username=root

; 连接数据库的密码，对应用户名的访问密码
password=123456

查看第三方数据库配置说明

配置校验

14.5.0及以上版本，集团服务在启动阶段新增了关键组件前置检查功能，该功能可快速识别MySQL配置异常问题，并输出明确错误提示。

• 错误信息格式

  通用错误提示（固定显示）+具体错误详情，其中通用错误提示固定为“Failed to connect to the MySQL database.”

• 错误示例：（根据实际情况显示）

[ERROR] Failed to connect to the MySQL database. Access denied for user 'user1'@'192.168.1.121' (using password: YES)
// 上述错误表明数据库用户名或密码错误，解决方案：检查并修正plugin_mysql.ini配置文件中的数据库用户名或密码。

集团服务基础配置

设置维护模式

集团服务维护模式是一种特殊运行状态，设置后将阻断新登录请求，但保持已登录客户端全部功能可用。

适用场景

• 系统升级维护：降低业务中断影响，保障已连接用户持续作业。
• 紧急故障隔离：防止故障扩散，为故障修复争取时间。

使用须知

• 13.4.6及以上版本的集团服务支持该功能。
• 设置后立即生效且持续保持，必须手动关闭才能恢复正常模式。

操作指导

1. 通过命令行方式设置

• 启用维护模式

./bit_service -runMode maintenance  # Linux示例

• 恢复正常模式

./bit_service -runMode normal  # Linux示例

• 查看当前服务状态

./bit_service -s  # Linux示例

2. 通过界面方式设置

登录集团授权管理中心，进入“配置管理” > “维护”页面，通过开关（启用/关闭）切换维护模式状态。

配置启用IPv6

集团服务支持IPv6可以解决客户端使用IPv6地址访问集团服务、弥补IPv4网络地址资源有限的问题。集团服务默认使用IPv4，在启用IPv6后，集团服务可以在双栈网络模式下运行，即集团服务可以拥有两个不同版本的IP地址：IPv4地址和IPv6地址，这两个IP地址都可以进行访问。

使用须知

• 请确保集团服务所在的操作系统已启用IPv6。
• 请确保集团服务版本支持IPv6功能，目前12.1.0.19580及以上版本的集团服务支持IPv6。

Windows集团服务开启IPv6功能

Windows集团服务支持使用配置文件开启IPv6功能。集团服务的配置文件存放于集团服务的安装目录下，文件名为bit_service.xml，可以用任何文本编辑工具打开，操作如下：

• 在系统桌面右下角的任务栏区域，单击集团服务的托盘程序，在弹出窗口中点击“打开集团授权安装目录”。
• 打开集团服务安装目录下的bit_service.xml文件，将下面红色字体的代码复制到文件中，开发商根据需要选择一种进行设置：only-仅支持IPv6、disable-不启用IPv6、enable-启用IPv4和IPv6兼容模式，不设置则默认为disable模式。
• 设置完成后，在托盘程序中重启集团服务生效。

<?xmlversion="1.0"encoding="UTF-8"?>
<BitAnswerSrvConfig>
<Ipv6>only|disable|enable</Ipv6>  <!-- only：仅支持Ipv6，disable：不启用Ipv6，enable：启用兼容模式 -->
</BitAnswerSrvConfig>

Linux集团服务开启IPv6功能

Linux集团服务支持使用配置文件和命令行开启IPv6功能，有两种方式：

配置文件开启IPv6

集团服务的默认安装路径为/opt/bitanswer/service，配置文件的文件名为bit_service.xml，可以用任何文本编辑工具打开，操作如下：

• 打开集团服务安装目录下的bit_service.xml文件，将下面红色字体的代码复制到文件中，开发商根据需要选择一种进行设置：only-仅支持IPv6、disable-不启用IPv6。
• enable-启用IPv4和IPv6兼容模式。
• 设置完成后，重启集团服务生效。

<?xmlversion="1.0"encoding="UTF-8"?>
<BitAnswerSrvConfig>
<Ipv6>only|disable|enable</Ipv6>  <!-- only：仅支持Ipv6，disable：不启用Ipv6，enable：启用兼容模式 -->
</BitAnswerSrvConfig>

命令行开启IPv6

在集团服务的Linux主机中执行以下命令，开启IPv6。

• 输入“su”，以管理员身份登录。
• 输入“cd /opt/bitanswer/service”，跳转到集团服务的默认安装路径/opt/bitanswer/service。
• 输入“./bit_service -c -ipv6 only|disable|enable”，开发商根据需要选择一种进行设置：only-仅支持IPv6、disable-不启用IPv6、enable-启用IPv4和IPv6兼容模式。
• 输入“./manager.sh stop”，停止集团服务。
• 输入“./manager.sh start”，启动集团服务。

配置SSL

SSL（安全套接层，Secure Sockets Layer）是一种安全协议，目的是为互联网通信，提供安全及数据完整性保障。

集团服务支持上传SSL证书，在使用HTTPS访问时，集团服务将SSL证书自动安装到服务器上，实现数据传输加密。服务器通过安装SSL证书可以实现数据信息在客户端和服务器之间的加密传输，可以防止数据信息的泄露，保证了双方传递信息的安全性。

使用须知

• 必须保证当前系统支持SSL库，否则启动时会报错。

操作指导

1. 新建文件ssl_key.pem，将数字证书和私钥拷贝进这个文件。如下图：

2. 然后将ssl_key.pem存放在集团服务的根目录。
3. 手动在bit_service.xml中添加SSL端口监听，如下图：

4. 最后重启集团服务，通过https://xxx:8276即可访问。

配置本地集团授权

本地集团授权功能允许将集团授权访问权限限制在部署集团服务的单台机器上，确保授权访问的本地化和安全性。

适用场景

• 仅允许特定机器访问集团授权的安全需求场景。

使用须知

• 该功能需要比特授权云平台支持，如果需要开通该功能，请联系比特安索。
• 设置后只有部署集团服务的机器可以访问该授权。

操作指导

• 开发商登录比特授权云平台，在指定SN的“授权信息”页签勾选“仅限本机访问”选项。
• 用户在集团服务端升级SN使设置生效。

配置二级代理

二级代理功能允许二级集团服务代理一级集团服务的部分用户数，供客户端使用，实现授权资源的层级分配和管理。

适用场景

• 需要实现多级授权管理的集团组织架构。
• 需要将总授权数分配给下级单位使用的场景。

使用须知

• 该功能需要比特授权云平台支持，如需开通此功能，请联系比特安索。
• 11.0.0及以上版本的集团服务支持该功能。
• 目前仅支持通过RESTful接口进行配置。

操作指导

1. 开发商登录比特授权云平台，在指定SN的“授权信息”页勾选“授权代理”选项。（如图）
2. 用户通过RESTful接口进行代理管理操作，包括：添加代理、释放代理、获取代理信息。

客户端心跳认证机制

客户端心跳认证机制是一种通过周期性发送心跳包来维持客户端与服务端连接活跃性的技术。该机制通过设置超时时间和心跳间隔，确保及时检测连接状态并回收异常连接资源。

功能特性

• 动态超时配置：默认客户端超时时间10分钟，可配置范围为1分钟~48小时。
• 智能心跳间隔：心跳间隔为超时时间的1/2，上限为10分钟（超时时间即使大于20分钟，心跳间隔也是10分钟）。超时未收到心跳则集团服务会踢出客户端并回收License，支持通过Bit_SetAttr()设置回调函数触发后续操作。

使用须知

• 需下载并安装最新版本的集团服务、客户端库。

集团授权管理中心设置客户端超时时间

登录集团授权管理中心，在“配置管理”页的“通讯设置”中设置客户端超时时间。

客户端连接集团服务

客户端连接配置提供了多种灵活的配置方式，开发商可以根据具体场景需求选择合适的配置方式，并遵循优先级顺序进行配置。

• 客户端支持3种方式配置连接集团服务的URL，包括环境变量、API传入和配置文件。
• 优先级顺序为：环境变量 > API传入 > 配置文件。这意味着如果多种配置方式同时存在，系统将首先使用环境变量的配置

适用场景

• 环境变量和API传入方式支持运行时动态修改，提高了配置的灵活性和效率。
• 配置文件方式相比环境变量和API传入方式灵活性较低，适用于较为稳定的配置场景。

使用须知

• 12.1.0.19580及以上版本的集团服务支持客户端通过配置环境变量连接。
• 13.0.0及以上版本的客户端库支持使用环境变量配置多个服务器地址。
• 13.4.7及以上版本的客户端库同时支持读取逗号和冒号分隔的环境变量。

环境变量方式连接服务

客户端与集团服务之间的连接方式默认是通过调用比特授权云的授权接口，客户端在本地配置IP地址和端口号实现。

环境变量配置方式有3种：使用默认环境变量名、API接口自定义环境变量名、比特授权云平台自定义环境变量名。

环境变量设置服务器地址

1. 默认环境变量设置服务器地址

示例：

BITANSWER_URL=bit://192.168.1.10:8273
# 默认变量名：BITANSWER_URL
# 服务器地址设置：bit://192.168.1.50:8273

2. API接口自定义环境变量设置服务器地址

比特授权云支持开发商自定义环境变量名，需要在程序中调用比特授权云的授权接口配合设置，设置后即可支持通过自定义环境变量连接。

开发商自定义变量名设置后（参见客户端库的自定义环境变量名操作），即可通过自定义环境变量进行连接。

示例：

XXXXX_URL=bit://192.168.1.10:8273
# 自定义变量名：XXXXX_URL
# 服务器地址设置：bit://192.168.1.50:8273

3. 比特授权云平台自定义环境变量名

参见《比特授权云 客户端SDK说明》“环境变量”章节。

设置环境变量

1. 客户端图形界面方式设置

   以Windows系统为例。

• 打开系统设置：右键点击「此电脑」→「属性」→「高级系统设置」→切换到「高级」选项卡（或按Win + R输入sysdm.cpl→切换到「高级」选项卡）
• 点击“环境变量”按钮，在弹窗中新建系统变量，设置服务器地址。

2. 客户端命令行方式设置

   以管理员权限操作。

setx /M BITANSWER_URL "bit://192.168.1.50:8273"
# 默认变量名：BITANSWER_URL
# 服务器地址设置：bit://192.168.1.50:8273

环境变量配置多个URL

当最终用户部署多个集团服务时，允许客户端的环境变量配置多个集团服务器的地址。当一台服务器挂死还有其他服务器可用，不会影响客户端授权，支持高可用场景。

• 13.0.0及以上版本的客户端库支持使用环境变量配置多个集团服务器的地址。13.4.7及以上版本的客户端同时支持读取逗号和冒号分隔的环境变量。
• 仅支持配置多个集团服务的地址，不支持与其他地址混用。
• 客户端连接集团服务的连接顺序，按照配置顺序依次连接，找到第一个可用的IP地址进行连接。
• 环境变量最多支持配置8个服务器地址，配置多个只有前8个生效。不同服务器地址之间以逗号或者冒号分隔，支持如下两种格式：

BITANSWER_URL= bit://192.168.1.1:8273:bit://192.168.1.2:8273
BITANSWER_URL= 8273@192.168.1.1:8273@192.168.1.2

其他说明

如果客户端集成时通过接口中设置了自定义环境变量，但是客户端设置环境变量时还是使用默认的BITANSWER_URL，默认环境变量也同样生效；如果环境变量同时设置了默认的BITANSWER_URL和自定义变量XXXXX_URL，XXXXX_URL优先级更高。

API传入方式连接服务

通过Bit_Login / Bit_LoginEx接口szURL参数自定义授权服务器地址。

配置文件方式连接服务

配置文件仅支持配置授权服务器地址。该配置机制主要用于集团授权场景，通过指定授权服务器地址实现局域网内的授权验证。

1. 配置文件位置与优先级

• 配置文件可存在于两个位置：一个是授权目录，一个是软件当前目录。
• 当两个位置的配置文件同时存在时，配置文件的优先级为：授权目录 > 软件当前目录。

2. 授权目录默认路径

• Linux：“{当前用户}/BitAnswer/{product-code}/bit_config.xml”

• Windows：“{系统盘}/ProgramData/BitAnswer/{product-code}/bit_config.xml”

  其中product-code为产品路径。

3. 配置文件内容格式

   采用XML格式定义授权服务器连接参数，包含以下关键字段：

   详细内容参见《比特授权云 客户端SDK说明》“配置文件”章节。

<?xml version="1.0" encoding="UTF-8"?>
<BitConfig>
    <Server Host="<集团服务IP>" Type="bit" Port="<集团服务端口>" Timeout="8" />
</BitConfig>

授权管理功能

授权借出

授权借出指的是从授权服务器借出一定的点数给客户端短期离线使用。

功能特性

• 允许客户端在离线模式下临时借用授权点数，支持到期后自动归还或通过调用接口主动归还。
• 仅支持已开启“借出属性”的集团授权和帐号授权类型。
• 支持功能级（feature）、时长（maxHours）和不可借出资源（reserve）的细粒度控制。
• API支持：提供Bit_CheckOutSn（授权借出）、Bit_CheckIn（主动归还）等专用API实现程序化操作。

适用场景

• 离线办公支持：员工脱离企业内网环境时仍可继续使用授权功能。例如：公司购买了集团授权供员工使用，但是有的员工需要在家里加班或者出差使用。

使用须知

• 如果比特授权云平台需要开通该功能，请联系比特安索。
• 13.4.8及以上版本的集团服务，支持禁用特定feature后不影响其他feature借出。（需配合13.4.8及以上版本的集团服务、集团扩展和客户端库）
• 14.4.0及以上版本集团服务，支持机器名相同且MAC地址不同的多台设备同时借出（此前版本不允许同名设备重复借出）。（需配合14.4.0及以上版本的集团服务、集团扩展）

比特授权云平台操作

比特授权云平台管理员在“授权”列表中创建授权码时，勾选授权信息中“授权借出”并保存，即可在集团授权管理中心中对该授权码进行借出操作。

对于已经创建的授权码，可以通过在“授权”列表中点击授权码，在“授权信息”页签勾选“授权借出”功能，保存后即可使用。

注意：允许授权借出勾选后不可解除。

集团授权管理中心操作

集团授权管理中心授权码的借出选项显示“-”代表没有开通借出功能。参见 授权码操作开通后，在集团授权管理中心对授权码进行升级。

已经开通借出功能的授权码如图所示：

配置借出规则

1. 借出规则类型

可以配置全局规则（适用于所有产品的统一配置）和指定产品规则（针对单个产品的个性化配置）。

• 支持BORROW ALLOW（允许借出）、BORROW DENY（禁止借出）和BORROW OPTIONS（借出选项）三种借出规则。
• 支持功能级（feature）、时长（maxHours）和不可借出用户数（reserve）的细粒度控制。

2. 配置方式

• 通过界面配置

登录集团授权管理中心，在“产品列表”页点击产品后面“设置”，设置访问规则。

示例：通过规则配置借出时间，规则设置以小时计算（如下图）

注意：集团授权管理中心默认最大可借出时间是30天，超过30天需要在规则中进行设置。借出可设最大时长为180天。

• 通过API配置

使用访问控制相关接口添加访问规则、删除访问规则、添加全局用户组、删除用户组里的用户，设置访问规则。

使用API执行借出/归还操作

在线：Bit_CheckOutSn、Bit_CheckIn（主动归还）、Bit_CheckOutFeatures

离线：Bit_GetBorrowRequest、Bit_ApplyBorrowInfo

详细调用说明参见线上API文档。

授权分发

比特授权云的集团授权支持“授权分发”功能，该功能允许借出一个永久授权到客户端使用（即最长借出时间为365*100天），并且借出的授权不允许返还。

使用须知

• 如果比特授权云平台需要开通该功能，请联系比特安索。
• 授权分发功能需下载并安装最新版本的集团服务后方可实现。
• 14.4.0及以上版本集团服务：授权分发处理能力显著提升，单台服务器性能达到1500个/秒，多台服务器分发性能按“部署台数 x 单台性能（1500个/秒）”的方式线性叠加，扩展过程无额外性能损耗或折减。

授权码操作

比特授权云平台管理员在“授权”列表中创建授权码时，勾选授权信息中的“授权分发”并保存，即可在集团授权管理中心中对该授权码进行分发操作。

对于已经创建的授权码，可以通过在“授权”列表中点击授权码，在“授权信息”页签勾选“授权分发”功能，保存后即可使用。

注意：一般在只勾选了“授权分发”时，会默认自动勾选“授权借出”功能。授权借出和授权分发勾选后不可解除。

集团授权管理中心操作

在集团授权管理中心激活授权码后，在“授权列表”中可以看到开通了授权分发功能的授权码后有“借出”功能。点击“借出”即可进行离线授权分发操作。

授权分发

在集团授权管理中心中的对应授权码后点击“借出”后，即可进入授权分发界面。

用户在需要离线借出的机器上生成对应的离线请求文件，获取离线文件后导出，在该界面中上传，点击“借出/返还”按钮可以获得一个对应的借出升级文件，将这个文件导入到生成离线请求文件的机器上升级使用，即可完成授权分发操作。

分发API使用

在线：Bit_CheckOutSn、Bit_CheckIn、Bit_CheckOutFeatures

离线：Bit_GetBorrowRequest、Bit_ApplyBorrowInfo

详细调用说明参见线上API文档。

SN重用特征项

SN重用特征项是指在SN层级独立创建的特征项，可以与产品级全局特征项同名且互不冲突，允许独立设置授权规则和绑定设备指纹。

功能特性

1. 集团服务

• 集团授权管理中心模块列表，支持显示SN关联的重用特征项列表。
• 对于已绑定设备的特征项，默认显示4位简略设备指纹信息，点击该设备的简略指纹可查看完整设备指纹信息。
• 采用特征项分组机制，同名特征项自动归为一组，峰值统计以组为单位显示。
• RESTful的“获取特征项列表并可查峰值信息”接口，支持查询SN重用特征项及分组峰值信息。

2. 优先级与使用规则

• 客户端Query占用特征项时遵循四级优先级：共用特征项（最高优先级） > 绑定了该设备的特征项 > 低版本特征项 > 剩余用户数多的特征项。
• 特征项使用分两种模式：未绑定设备的特征项，对所有设备开放使用；已绑定设备的特征项，仅对预设客户端开放使用。

适用场景

• 授权绑定硬件，实现精准的设备访问控制：通过将客户端的设备指纹（如MAC、终端标识、IP等）写入授权文件，在客户端登录时系统自动校验硬件匹配性，确保软件仅能在预设的硬件设备中运行。适用于需要严格防止授权跨设备共享或未授权非法迁移的高安全场景。
• 特征项动态组合，灵活分配差异化功能权限：功能特征项（如特定模块或权限）按业务逻辑分组管理时，同一特征项可跨多个业务组复用并独立设置配额（如用户数限制），最终生成的授权文件整合所有特征项的并集。这种方式可以实现多部门权限隔离（如财务部门仅开放报销模块权限）、跨项目资源复用（如同一审批流程可同时分配给项目A和项目B，并分别设置10人/20人配额），确保权限分配既满足最小化原则，又适应企业组织结构的动态调整。
• 资源动态扩展，无需新生成授权：通过叠加式授权机制，开发商管理员可以针对同一功能特征项多次授权（如延长有效期或增加用户数配额），系统在验证时会自动合并计算多次授权的资源总量。实现1）资源扩展无中断：新增授权与原始授权并行生效，避免覆盖原有配置；2）精细化管理：每次扩展可独立设置有效期或用户数配额，满足临时扩展或长期增量需求。

使用须知

• 仅限集团授权类型使用，不支持其他授权类型。
• 版本要求：客户端、集团扩展模块、集团服务、Backoffice API需使用14.0.0及以上版本，E3需保持最新版本。
• 特征项绑定设备类型：支持输入原始MAC和带“#”前缀的终端标识（如#Device123）；14.3.0及以上版本，在14.0.0版本基础上，额外支持绑定IP。（需要配合14.3.0.及以上版本的集团服务）
• BitStat工具不支持SN重用特征项功能。
• 兼容性：使用14.0.0及以上版本客户端配置更新后，需保持版本一致性，严禁版本回退操作，以避免可能引发的兼容性问题。

比特授权云平台操作

比特授权云平台支持为SN添加、删除、修改重用特征项（Overloaded Feature），提供手工录入和批量文件导入两种特征项添加方式，且添加数量不作限制。每个特征项可独立设置设备指纹（MID），单特征项最大允许关联1000个MID。

1. 开启“允许特征项绑定设备”功能

为特征项手工录入或批量导入设备前，需先开启“允许特征项绑定设备”功能。

• 登录比特授权云平台 > 设置 > 品牌化，勾选“允许特征项绑定设备”选项。
• 成功开启后，在授权码“特征项”页签的特征项列表中会显示“设备”列。

2. 添加SN重用特征项

• 手工录入

进入授权码“特征项”页签 > 点击“导入”按钮，在弹窗中选择“手动添加”进行特征项追加操作。

• 文件导入

进入授权码“特征项”页签 > 点击“导入”按钮，在弹窗中选择“上传文件”进行特征项追加操作。

文件格式规范：

FEATURE feature feat_version exp_date num_lic [mid/hostid="xxxx"]

注意事项：

• 文件文本应为UTF8格式（如：.txt）。
• 每行一个特征项，参数间用单个空格分隔。
• 参数顺序不可调换。
• 导入内容全部为追加方式。

参数说明：

• FEATURE：固定标识符。
• feature：特征项名称
• feat_version：特征项值或特征项版本，4字节无符号整型数值表示特征项值（如10），浮点型数值表示特征项版本（如10.0）。
• exp_date：结束日期或有效期，yyyy-MM-dd格式表示结束日期（如2025-6-11），数字表示有效期（如365），unlimited表示永久有效。
• num_lic：用户数，unlimited表示无限。
• mid/hostid（可选）：绑定设备指纹，单个值无需双引号（如 mid/hostid=00A1B2），多个值需用双引号包裹并以空格分隔（如 mid/hostid="00A1B2 00C3D4"），最大允许输入1000个。仅支持输入原始MAC和带”#”前缀的终端标识（如#Device123）。

说明：

• 14.0.0及以上版本，支持输入原始MAC和带“#”前缀的终端标识（如#Device123）。


• 14.3.0及以上版本，在14.0.0版本基础上，额外支持绑定IP，IP格式包括三种类型：单IP（如127.0.0.1）、通配符后缀（如127.0.0.*）、指定IP段（如127.0.0.0-127.0.0.255）。（需要配合14.3.0.及以上版本的集团服务）

示例：

FEATURE featureName001 10.0 unlimited unlimited [mid/hostid="00A1B2 00C3D4"]  # 指定多个MAC
FEATURE featureName001 10.0 unlimited unlimited [mid/hostid="127.0.0.0-127.0.0.255"]  # 指定IP段

3. 删除SN重用特征项

在授权码“特征项”页签的特征项列表中，取消勾选特征项，对应项即可删除。

4. 修改SN重用特征项

允许修改SN重用特征项的用户数、有效期、结束日期、设备指纹。

在授权码“特征项”页签的特征项列表中，有效期/用户数/结束日期直接编辑对应字段，设备指纹则点击设备列的电脑图标进行编辑。

集团授权管理中心操作

1. 显示SN重用特征项及绑定设备

集团授权管理中心模块列表，支持显示SN关联的重用特征项列表。对于已绑定设备的特征项，默认显示4位简略设备指纹信息，点击该设备的简略指纹可查看完整设备指纹信息。

2. 显示SN重用特征项峰值

采用特征项分组机制，同名特征项自动归为一组，峰值统计以组为单位显示。

使用分析功能

SN用量统计

要为集团授权的授权码增加“强制认证”和“用量统计”功能，操作如下。

适用场景

该功能适用于后付费模式下的集团授权管理场景，通过强制认证机制确保用量数据定期上报，用于监控和统计实际使用量计费。

使用须知

• 如果比特授权云平台需要开通该功能，请联系比特安索。
• 用量统计功能需下载并安装最新版本的集团服务后方可实现。

授权码操作

比特授权云平台管理员在“授权”列表中创建授权码时，勾选授权信息中的“强制认证”和“用量统计”并保存。当授权码激活后，客户端在每个强制认证周期内连接服务器认证时，必须将用量统计上传，否则无法继续使用授权。

对于已经创建的授权码，可以通过在“授权”列表中点击授权码，在“授权信息”页签勾选“用量统计”功能，保存后即可使用。

注意：用量统计勾选后不可解除。

集团授权管理中心操作

已经开通用量统计功能的授权码在激活后再次点击升级时，会弹出“请上传用量数据”的提示，点击“手动上传”，集团服务将会自动生成一个后缀为“.log”的加密日志文件，文件存储在所使用的浏览器的默认下载文件位置。

用户授权中心操作

用户获得日志文件后，需要在比特云用户授权中心（user.bitanswer.cn）里上传，上传成功后方可进行升级操作。

使用需要激活的授权码登录用户授权中心，点击左侧“离线升级”。

在“选择文件”中选择对应log文件，点击上传，将文件上传至服务器，上传成功后即可返回集团授权管理中心完成升级，否则将无法升级该授权码。

查看SN用量统计

集团服务用户上传用量统计数据后，平台管理员可以通过授权码查看到客户上传的用量统计信息。

管理员点击已勾选用量统计的授权码进入“授权信息”页签，点击页面中的“使用记录”，即可看到用量统计上传的信息。

SN峰值自动上传

集团服务支持将SN和Feature的峰值上传到授权服务器，上传到服务器后，开发商可以通过调用backoffice接口获取到峰值数据。

适用场景

开发商监控峰值数据。

使用须知

• 13.2.1及以上版本的集团服务支持将SN和Feature的峰值上传到授权服务器。
• 如果需要开通该功能，请联系比特安索。授权码的峰值上传功能一旦勾选不可解除。

操作指导

1. 使用该功能前需在比特授权平台中勾选授权码的峰值上传的“用量统计”属性。

2. 再在集团服务中激活具有峰值属性的授权码，点击授权码的空白处，点击上传按钮，即可将峰值数据上传。

3. 调用backoffice接口获取到峰值数据，数据格式如下：

#type:userPeakLog sn:xxxxxx time:导出时间 sign:<下面是整个串的签名>
[
    {
        time: 2024-05-09
        feature: { <uid>:<peak>, <uid>:<peak> },
        sn: <peak>
    },
    {
        time: 2024-05-10
        feature: { <uid>:<peak>, <uid>:<peak> },
        sn: <peak>
    },
    {
        time: 2024-05-11 // 不传feature和SN 表示其数据为0
    }
]

自定义特征组数据合并统计

用户可以将多个特征项定义成一个组（简称“特征项组”），集团服务会自动统计该特征项组的登录数据（如实时在线数量、峰值等）。

使用该功能前，用户需先登录集团授权管理中心的规则设置界面，通过DEFINE LIST关键字完成特征项组的定义。

功能特性

• 灵活配置特征项组：可通过DEFINE LIST规则自定义特征组列，支持配置任意数量、不同名称的特征项组。
• 数据合并统计：集团服务会自动统计特征项组的登录数据（如在线用户数、峰值）。需注意，特征组名称为该组的唯一标识，若修改名称，将被视为新建特征项组，原有统计不再延续。

适用场景

用户需要统计某一类关联功能的整体峰值时，就可以使用该功能。

示例：某SN包含特征项“复制1.0”、“复制2.0”、“复制3.0”，若用户想获取“复制”功能的总峰值。用户需先定义一个特征项组：

DEFINE LIST 复制 “复制[version=1.0]” “复制[version=2.0]” “复制[version=3.0]”

定义完成后，集团授权管理中心的特征项列表中会新增“复制”特征项组。

使用须知

• 仅适用于集团授权类型，其他授权类型不支持使用。
• 版本要求：集团服务需使用14.3.0及以上版本。

操作指导

1. 配置特征项组

将需要合并统计登录数据（如峰值）的多个特征项配置为同一特征项组，具体操作如下：

登录集团授权管理中心，进入产品列表的“操作 > 设置”菜单，通过DEFINE LIST规则定义特征项组。

访问规则的设置方式请参见“产品访问规则帮助”。

2. 查看数据合并统计结果

特征项组配置完成后，在集团授权管理中心的模块列表页面顶部，可查看各特征项组的数据合并统计结果（如峰值）。该区域通过不同的行背景色与单一特征项进行区分，包括“峰值 (月 / 年)”列及“峰值统计图”详细信息，支持多维度查看统计结果。

访问控制功能

配置群组白名单规则

使用须知

• 13.7.0及以上版本的集团服务支持按群组配置白名单规则。

集团授权管理中心配置群组白名单

1. 准备白名单文件

• 文件名格式：group.组名.txt

示例：group.manager.txt，（组名为manager）

• 文件内容规则

文件中的每行仅包含一个客户端，允许格式：用户名（如zhangshan）、机器名（以@开头，如@PC-01）、或单一IP地址（如192.168.0.1）。

文件不超过5000行，8秒内完成导入，超过则可能导致导入时间过长。

示例：

zhangsan
@PC-01
192.168.0.1

2. 导入白名单文件

• 登录集团授权管理中心，在产品列表的“操作 > 设置”中，点击“导入规则”按钮，选择本地白名单文件（如：group.manager.txt）进行导入操作。
• 导入成功后，页面提示“#全局规则，来自本地文件”，在全局规则的下方，会自动生成一条规则“ALLOW group:manager”。
• 配置多条规则：一个产品可以添加多组全局规则，如果需要，可以多次进行导入操作。

3. 修改或更新白名单

• 将改后的group.manager.txt重新上传，系统将覆盖旧规则。

RESTful接口配置群组白名单

RESTful新增添加全局用户组、删除用户组里的用户、查询用户组里的用户接口，支持在规则中进行白名单管理。

状态监控功能

配置Prometheus监控

14.5.0及以上版本的集团服务支持配置Prometheus监控，开发商可以根据实际需求启用该功能，实现对集团服务关键指标的实时监控与预警。

适用场景

Prometheus监控核心适用场景包括：

• 特征项或SN剩余用户数少于阈值时触发提醒。
• SN或特征项状态异常变化时触发预警。
• 服务器负载过大时触发预警。
• 服务产生ERROR（错误级别）和WARN（警告级别）日志时触发告警。

使用须知

• 集团服务版本要求：14.5.0及以上版本支持该功能。
• Prometheus版本要求：使用安全、稳定、可靠的版本，建议使用3.5.0及以上版本。

集团服务指标配置

集团服务Metrics协议

集团服务提供符合Prometheus规范的metrics协议，Prometheus可通过该协议获取指定维度的监控指标数据，支持按产品、特征项等条件筛选采集。

• 地址格式：http://<集团服务IP>:<管理端口>/metrics?productId=&featureName=&hasFeature=
• 地址参数说明：

支持的监控指标列表

集团服务提供用户数、状态、服务负载三类核心指标，这些指标可用于Prometheus监控的自定义告警规则配置，具体说明如下：

操作指导

前提条件

已成功部署Prometheus软件。（部署流程参考Prometheus官方文档）

自定义告警规则配置

按以下步骤创建并配置告警规则：

1. 创建规则目录：在Prometheus配置目录下创建规则目录（如prometheus/group）。
2. 创建告警规则文件：在规则目录下，创建集团服务告警规则文件（格式为.yml，如prometheus/group/sn_alerts.yml）。
3. 配置告警规则文件：单个规则文件包含groups（规则组）列表，每个组内可包含多个规则，其中的expr指标表达式需参考“支持的监控指标列表”。以下为4类典型场景的规则文件示例：

• 场景1：SN剩余用户数小于10时告警

groups:
- name: sn_users  # 规则组名称（必须唯一）
  rules:
    # SN剩余用户数小于10时告警
    - alert: SnRemainingUsersTooLow  # 规则名称（必须唯一）
      expr: sn_users - sn_users_online < 10  # 表达式：每个SN的总用户数 - 在线用户数 < 10时触发
      for: 1m                 # 持续1分钟时触发，避免瞬时波动
      labels:
        severity: warning     # 标签（如warning、error、info）
      annotations:
        summary: "SN {{ $labels.sn }} 剩余用户数过低"   # 告警概要
        description: "SN {{ $labels.sn }} 的剩余用户数（总用户 - 在线用户）为 {{ $value | humanize }}，已低于阈值10人，持续1分钟。"   # 告警详细描述
        # 显示当前SN的剩余用户数（直接通过计算结果获取）
        current_remaining: "当前剩余用户数：{{ $value | humanize }}"

• 场景2：SN状态变化时告警

groups:
- name: all_sn_status_alerts
  rules:
    # 告警1：任何SN的状态从正常（0）变为异常（非0）
    - alert: AnySnStatusChangedToAbnormal
      expr: sn_status != 0  # 匹配所有SN，状态不等于0（发生变化）
      for: 2s  # 持续2秒确认变化（防抖动）
      labels:
        severity: warning
      annotations:
        summary: "SN状态异常变化"
        description: "SN {{ $labels.sn }} 的状态从正常（0）变为 {{ $value }}，当前异常。"
        current_status: "状态值：{{ $value }}"

    # 告警2：任何SN的状态从异常恢复为正常（0）
    - alert: AnySnStatusRecoveredToNormal
      expr: sn_status == 0  # 匹配所有SN，状态恢复为0
      for: 2s
      labels:
        severity: info
      annotations:
        summary: "SN状态恢复正常"
        description: "SN {{ $labels.sn }} 的状态已从异常恢复为正常（0）。"

• 场景3：服务队列长度大于100时告警

groups:
- name: service_monitor_alerts
  rules:
    # 告警2：队列长度超过1（新增）
    - alert: ServiceQueueLengthExceeded
      expr: service_queue_length > 100  # 队列长度>100时触发
      for: 5s  # 持续5秒确认（避免瞬时抖动）
      labels:
        severity: warning
      annotations:
        summary: "服务队列长度超限"
        description: "当前队列长度为 {{ $value }}，已超过阈值1，请关注处理延迟。"
        current_length: "当前队列长度：{{ $value }}"

• 场景4：服务新增Error时告警

groups:
- name: service_error_alerts
  rules:
    - alert: ServiceErrorsIncreased
      # 表达式：过去5分钟内错误数有新增（>0）
      expr: increase(service_error_total[5m]) > 0
      for: 10s  # 持续10秒确认新增错误
      labels:
        severity: critical
      annotations:
        summary: "服务错误数增加"
        # 仅使用 $value 表示新增错误数，不做运算
        description: "过去5分钟内新增错误 {{ $value | humanize }} 个，请及时排查。"
        # 提示用户查询累计值的方式
        tip: "当前累计错误数可在 Prometheus 中查询指标：service_error_total"

修改Prometheus配置（对接集团服务）

修改prometheus.yml配置文件，配置内容包含全局配置（global）、告警规则配置（rule_files）、数据采集源配置（static_configs）三部分。具体说明如下：

1. 全局配置

全局配置是所有其他配置的默认值，可被局部配置覆盖，配置时应平衡时效与性能。

global:
  scrape_interval: 30s      # 数据采集时间间隔，建议设为30s，平衡实时性与性能
  evaluation_interval: 15s  # 执行告警规则的时间间隔
  scrape_timeout:10s        # 采集超时时间

2. 告警规则配置

用于指定告警规则文件路径，将“自定义告警规则”创建的规则文件进行替换。

rule_files:
  - "group/sn_alerts.yml"   # 单个文件，替换为实际的规则文件路径
  - "group/*.yml"           # 目录下所有yml文件
  - "!group/error.yml"      # 排除特定文件

3. 数据采集源配置

用于定义监控目标，即集团服务的地址与筛选条件。

static_configs:
  - job_name: "sn_user_metrics_with_params"  # 必填，采集任务名称（必须唯一）
   scrape_interval: 10s  # 可选，该任务的采集间隔，设置后可覆盖全局配置
   scrape_timeout: 10s   # 可选，该任务的采集，设置后可覆盖全局配置
    static_configs:
      - targets: ["192.168.0.xx:8274"]  # 必填，集团服务的指标暴露地址，格式为<集团服务IP>:<管理端口>
      metrics_path: "/metrics"  # 必填，指标数据的访问路径（固定值为/metrics，不可修改）
      params:  # 可选，指标筛选配置，支持的筛选参数参见“集团服务Metrics协议”
        productId: ["PE-PE"]    # 可选，按产品筛选查询，设置后仅返回指定产品的信息
        featureName: ["测试"]   # 可选，按特征项名称筛选查询，设置后仅返回指定特征项的信息
        hasFeature: ["true"]    # 可选，用于指定是否返回feature的统计信息，设置为ture则显示feature信息

重启prometheus与配置验证

完成上述文件修改后，需重启Prometheus使配置生效。通过访问Prometheus控制台，验证数据采集是否正常、告警规则是否生效。

常见问题排查

当出现告警未触发的情况时，可按照以下步骤进行排查：

1. 检查告警规则：查询告警规则表达式（如sn_users - sn_users_online < 10），确认是否满足触发条件。
2. 检查规则加载：进入Prometheus的Alerts页面，确认告警规则是否已加载，状态是否为OK。
3. 检查评估间隔：确认global.evaluation_interval配置是否合理，避免间隔过长导致告警延迟。

第三方接入功能

配置第三方链接

集团服务支持通过RESTful接口配置第三方链接，配置数量无上限；配置完成后，链接访问入口将在集团授权管理中心展示。

适用场景

开发商或最终用户可以将第三方链接，通过RESTful接口配置集成至集团服务，实现用户在集团服务内点击该链接，即可无需跳转至外部系统入口，即可直接跳转至访问第三方指定链接对应的页面的场景。

使用须知

• 集团服务版本要求：14.5.5及以上版本支持该功能。
• 展示规则：通过RESTful接口添加第三方链接后，集团授权管理中心界面才会同步展示对应的跳转链接按钮。
• 异常处理：集团服务重启后，已配置的第三方链接信息将全部丢失；为保障链接信息持续有效，第三方服务需定期调用RESTful接口重新添加链接，建议调用频次为1次/分钟。

操作指导

前提条件

• 已获取待操作产品的产品编号，该编号可通过执行命令行指令-p查询。
• 已准备好待集成第三方页面的有效访问地址，以及该链接的相关描述信息。

添加第三方跳转链接

1. 配置外部链接信息：调用RESTful添加第三方链接接口，完成外部链接信息配置；配置完成后，该链接的访问入口将在集团授权管理中心展示。
2. 查看已配置链接：在产品列表中，进入对应产品的日志页，可查看到新建的外部跳转链接按钮。单击按钮可直接跳转到目标外部页面；若配置链接时填写了描述信息，鼠标悬浮至该按钮时，将展示对应的描述内容。

查询第三方跳转链接

支持以下两种方式查询已配置的第三方链接：

• RESTful接口查询（推荐）：调用RESTful获取第三方链接接口查询，支持按key精准查询或按product批量查询该产品下所有链接。
• 集团授权管理中心界面查询：在产品列表中，进入对应产品的日志页，可查看到已配置的外部跳转链接按钮。

删除第三方跳转链接

1. 执行删除操作：调用RESTful删除第三方链接接口完成删除。
2. 验证删除结果：在产品列表中，进入对应产品的日志页，已删除的第三方链接按钮将不再显示，即代表删除操作生效。