协同授权

概述

SpreadJS 协同组件（Collaboration Add-on）需要服务器端授权验证，从 SpreadJS V19.0 开始新增服务器授权，通过双重授权校验（部署授权+服务器授权）保障生产环境的安全性与合规性。

服务器端授权需同时配置部署授权（licenseKey）和服务器授权（serverLicenseKey），客户端需按 SpreadJS 插件授权规范单独获取授权。本文档详细说明中文环境下的授权配置、流程、规则及故障处理，适用于开发测试与生产部署场景。

说明，完整的协同授权包含两部分：
1. 前端（SpreadJS 客户端）部署授权，且授权包含协同组件。前端部署授权的使用方式，可以参考：试用版和许可信息
2. 协同服务器授权，服务器激活时，需要使用前端部署授权以及服务器授权。

申请协同功能的服务器授权 (serverLicenseKey)，需要 SpreadJS 部署授权 (licenseKey) 和机器ID，申请时请一并提交。

快速开始

激活流程（新部署服务器）

获取机器ID：在目标服务器上调用 getMachineIdForServerLicense()，获取唯一机器ID。代码如下：

import { getMachineIdForServerLicense } from '@grapecity-software/js-collaboration';
// 获取机器ID（用于申请服务器授权）
const machineId = getMachineIdForServerLicense();
console.log('机器ID:', machineId);

申请授权：将机器ID 及SpreadJS 部署授权 (licenseKey) 提交给支持团队，申请对应的 serverLicenseKey（请确认部署授权 licenseKey 已包含协同组件）；

配置授权：在服务器代码中同时设置 licenseKey 和 serverLicenseKey，启动服务即可完成激活。

import express from 'express';
import { createServer } from 'http';
import { Server } from '@grapecity-software/js-collaboration';

const app = express();
const httpServer = createServer(app);
const server = new Server({ httpServer });

// 部署授权
server.licenseKey = "XXXXXXXXXXXXXXXXXXXX";
// 服务器授权
server.serverLicenseKey = "YYYYYYYYYYYYYYYYYYY";

反激活流程（服务器迁移/下线）

执行反激活：在原服务器上调用 deactivateServerLicense()，获取反激活凭证（token）；

注意：一旦执行了 deactivateServerLicense() ，则服务器将处于非激活状态。请谨慎执行该代码。

import { deactivateServerLicense } from '@grapecity-software/js-collaboration';
// 执行反激活并获取凭证
const result = deactivateServerLicense();
console.log('反激活凭证:', result[0].token); // 提交该token给支持团队完成解绑
console.log('反激活机器 ID:', result[0].machineId); // 提交该机器ID给支持团队完成解绑

提交凭证：将部署授权（licenseKey），token 和机器 ID（machineId）提交给支持团队，释放原服务器的授权绑定；
新服务器激活：在新服务器上重复「激活流程」，使用原部署授权（licenseKey）或新申请的部署授权（licenseKey）完成绑定。

查看授权状态（是否已激活）

要查看协同服务器是否已经正常激活，需要在 SpreadJS 客户端通过事件监听来判断，步骤如下：

按 SpreadJS 插件授权要求配置客户端 licenseKey，启用协同功能；

查看授权状态，可监听连接实例的 licenseValidation 事件，获取完整验证结果。

import { Client } from "@grapecity-software/js-collaboration-client";
const url = '服务器地址', roomId = '协同房间ID';
const client = new Client(url);
const connection = client.connect(roomId);

// 监听授权验证结果
connection.on('licenseValidation', (data: ILicenseValidationResult) => {
  console.log('授权验证结果:', data);
});

核心概念

服务器端新增属性

属性名	用途	说明
`serverLicenseKey`	服务器授权校验	独立于 `licenseKey`，需单独申请，用于验证服务器部署合法性

授权验证结果

ILicenseValidationResult 新增服务器授权相关字段，完整结构如下：

type LicenseType = 'evaluation' | 'production' | 'invalid' | 'no key';

interface ILicenseValidationResult {
  status: number; // 0=验证失败，1=验证成功
  message?: string; // 错误信息（验证失败时返回）
  type?: LicenseType; // 部署授权类型（licenseKey对应的状态）
  expiredDate?: string; // 部署授权过期日期（格式：YYYYMMDD）
  serverKeyType?: LicenseType; // 服务器授权类型（serverLicenseKey对应的状态）
  serverKeyExpiredDate?: string; // 服务器授权过期日期（格式：YYYYMMDD，永久授权不返回）
}

核心规则

双授权要求：非本地环境必须同时配置 licenseKey 和 serverLicenseKey，缺一不可，且必须版本匹配；
localhost 测试：未配置授权时，服务器仅允许 localhost 访问（测试环境），非本地请求会被拒绝；
授权兼容性：serverLicenseKey 使用新版产品码生成，不兼容 V19.0 之前的部署授权；
请求限制，协同服务器能相应的请求如下：
- 用于测试的本地请求，即 localhost
- 在部署授权 licenseKey 和服务器授权 serverLicenseKey 匹配的前提下，可响应 SpreadJS 客户端发送的请求。

支持环境

以下操作系统和部署平台为经过测试的环境：

操作系统

Linux：Ubuntu 22.04/24.04、RedHat Enterprise Linux 10.0、Debian 12.8/13.2、Rocky Linux 9.5、AlmaLinux 9.5；
Windows：Windows 11 中文版、Windows Server 2019/2022 数据中心版（64位）；
macOS：MacOS Sequoia 15.1.1；
国产系统：麒麟高级服务器操作系统V10（X86）、Alibaba Cloud Linux 3.2104 LTS、openEuler 22.03 LTS、AnolisOS 8.10（X86_64）。

部署平台

容器化：Docker（需要支持数据卷挂载持久化）；
容器编排：Kubernetes（Deployment/StatefulSet+PVC/emptyDir）；
云服务器：ECS 云服务器（支持实例重启、规格变更，更换系统/主机名需重新授权）。

故障排除

错误类型	本地访问（localhost）	非本地访问	解决方案
无授权配置	允许访问（测试模式）	拒绝，提示“未找到授权信息”	联系支持团队申请或购买授权，并配置有效的 `licenseKey` 和 `serverLicenseKey`
服务器未授权	拒绝，提示“当前机器未授权”	拒绝，提示“当前机器未授权”	联系支持团队，提供 `licenseKey` 和 `serverLicenseKey` 以确认 Key 是否有效，或重新申请授权。
授权信息不匹配	拒绝，提示“serverLicenseKey与licenseKey信息不匹配”	拒绝，提示“serverLicenseKey与licenseKey信息不匹配”	联系支持团队，提供 `licenseKey` 和 `serverLicenseKey` 以确认 Key 是否有效。
授权过期	拒绝，提示“授权已过期”	拒绝，提示“授权已过期”	联系支持团队，申请续期或更换有效授权。
授权解析失败	拒绝，提示“无效授权信息”	拒绝，提示“无效授权信息”	检查授权是否完整，无多余空格或字符缺失。或联系支持团队以确定 Key 是否有效。
产品类型无效	拒绝，提示“无效授权信息”	拒绝，提示“无效授权信息”	或联系支持团队以确定 Key 是否有效。
版本不兼容	拒绝，提示“版本不匹配”	拒绝，提示“版本不匹配”	确认 SpreadJS 版本是否与 Key 的版本匹配。或联系支持团队寻求帮助。

常见问题

Q：同一授权能否用于多台服务器？
A：默认不支持，serverLicenseKey 与单台机器ID绑定；如需多机部署，需联系支持团队申请多机授权。
Q: 容器化部署，应该如何使用授权？
A：对于容器化部署，请联系支持团队获取授权相关的信息。