Jira

从 Atlassian Marketplace 添加连接器

1. 以管理员身份登录您的 Jira Software 实例。
2. 点击右上角的 管理 图标，并从菜单中选择 管理应用 选项。
   
3. 将打开 查找新应用 部分。点击 搜索 Marketplace 字段，找到 Jira ONLYOFFICE 集成应用。
4. 点击 安装 按钮以下载并安装应用程序。

添加从源代码编译的连接器

首先，您需要安装以下先决条件才能编译 ONLYOFFICE 连接器到 Jira：

• Oracle Java SE Development Kit 8 的 1.8.X 版本
• Atlassian Plugin SDK

要编译 ONLYOFFICE 连接器到 Jira，请按照以下步骤操作：

1. 克隆 onlyoffice-jira 仓库。

   git clone https://github.com/ONLYOFFICE/onlyoffice-jira.git

2. 进入 onlyoffice-jira 目录。

   cd onlyoffice-jira

3. 运行以下命令：

   atlas-package

   等待连接器编译完成。之后，连接器可以在 target 文件夹中找到。

您可以在 Jira 软件管理 > 管理应用 页面上传编译的连接器。

1. 以管理员身份登录您的 Jira Software 实例。
2. 点击右上角的 管理 图标，并从菜单中选择 管理应用 选项。
3. 在页面左侧选择 管理应用 部分。
4. 点击 上传应用 链接。
5. 点击 选择文件 按钮，浏览编译的 target/onlyoffice-jira-app.jar 文件并点击 上传。等待应用程序安装完成。
   

配置 ONLYOFFICE 连接器到 Jira

在 管理应用 页面上，点击已安装的 Jira ONLYOFFICE 集成应用 下方的 配置 按钮，或在 管理应用 页面的 其他 部分找到该应用。

文档服务器

1. 在 文档编辑服务地址 字段中，指定安装了 ONLYOFFICE 文档 的服务器的 IP 地址或主机名。
   ONLYOFFICE 文档 的地址必须可以从 Jira 访问，同时 Jira 的地址也必须可以从 ONLYOFFICE 文档 访问。
2. 禁用证书验证（不安全） - 勾选此框以禁用证书验证，并允许 Jira 与 ONLYOFFICE 文档 建立连接，如果您使用的是自签名证书（否则，Jira 将不验证自签名证书，并不允许与 ONLYOFFICE 文档 的连接）。这是一个不安全的解决方案，我们强烈建议您将证书替换为由某个 CA 颁发的证书。
3. 指定一个 密钥（留空以禁用） - 用于在请求 ONLYOFFICE 文档 时验证 JSON Web Token 的密钥。
   从 ONLYOFFICE 文档 v7.2 开始，JWT 默认启用，并自动生成密钥。您需要在 Jira 端也启用它：在 ONLYOFFICE 文档配置文件 中找到您的密钥，然后在连接器设置中指定相同的密钥。有关更多详细信息，请参阅本文的 启用 ONLYOFFICE 和 Jira 集成的 JWT 部分。
4. 授权头（留空以使用默认头） - ONLYOFFICE 中使用的授权 JWT 头是 Authorization。如果此头与您的设置冲突，您可以将其更改为自定义头。
5. 连接到演示 ONLYOFFICE 文档服务器 - 启动测试服务器。
   重要这是一个公共测试服务器，将在 30 天内可用。请勿在此处共享您的敏感数据。

高级服务器设置

如果您的网络配置不允许使用公共地址在已安装的 Jira Software 和 ONLYOFFICE 文档 之间进行请求，则可以使用 高级服务器设置 部分。在这种情况下，请在相应字段中指定内部请求的地址：

1. 文档编辑服务的内部请求服务器地址 - Jira Software 服务器 的内部请求地址，用于 ONLYOFFICE 文档
2. 服务器的内部请求文档编辑服务地址 - ONLYOFFICE 文档 的内部请求地址，用于 Jira Software 服务器

通用设置

1. 可编辑格式 - 勾选您 Jira 环境支持的格式旁边的复选框。

   由于格式限制，保存时可能会丢失数据。

2. 编辑器界面 - 自定义编辑器的界面：
   • 显示聊天菜单按钮 - 隐藏/显示左侧面板上的在线内置 聊天 图标。
   • 显示更紧凑的标题 - 隐藏/显示顶部工具栏上的图标文本。
   • 显示反馈和支持菜单按钮 - 隐藏/显示左侧面板上的 反馈和支持 按钮。
   • 显示帮助菜单按钮 - 隐藏/显示左侧面板上的 帮助 按钮。
   • 显示单色工具栏标题 - 将顶部工具栏切换为单色调色板。

安全性

1. 启用插件 - 启用/禁用编辑器的插件支持。
2. 运行文档宏 - 启用/禁用在编辑器中运行宏。
3. 启用文档保护 - 选择是否允许 所有用户 启用文档的密码保护，或仅允许文档 所有者。

点击 保存 以保存设置。

工作原理

ONLYOFFICE 集成遵循 此处记录的 API。

1. 用户导航到 Jira 附件并选择 在 ONLYOFFICE 中编辑 操作。
2. Jira 向 OnlyOfficeEditorServlet 发送请求（URL 形式为：/plugins/servlet/onlyoffice/doceditor?attachmentId=$attachment.id）。
3. Jira 将文档发送到 ONLYOFFICE 文档存储服务并接收一个临时链接。
4. Jira 准备一个包含以下属性的 JSON 对象：
   • url: ONLYOFFICE 文档 用于下载文档的临时链接；
   • callbackUrl: ONLYOFFICE 文档 用于通知文档编辑状态的 URL；
   • docserviceApiUrl: 客户端需要回复 ONLYOFFICE 文档 的 URL（由 files.docservice.url.api 属性提供）；
   • key: 指示 ONLYOFFICE 文档 是否再次下载文档的 UUID；
   • title: 文档标题（名称）。
5. Jira 使用这些值构建一个页面，以便客户端浏览器可以加载编辑器。
6. 客户端浏览器向 ONLYOFFICE 文档 的 JavaScript 库发送请求，并将上述属性的 DocEditor 配置发送给 ONLYOFFICE 文档。
7. 然后 ONLYOFFICE 文档 从文档存储下载文档，用户开始编辑。
8. 当所有用户和客户端浏览器完成编辑时，他们关闭编辑窗口。
9. 在10 秒不活动后，ONLYOFFICE 文档 向 callbackUrl 发送 POST，通知 Jira 客户端已完成文档编辑并关闭。
10. 带有所有更改的文档将作为新附件保存，并在文件名中添加后缀。

启用 ONLYOFFICE 和 Jira 集成的 JWT

为了保护文档免受未经授权的访问，ONLYOFFICE 编辑器使用 JSON Web Token (JWT)。令牌 在文档编辑器初始化时添加到配置中，并在内部 ONLYOFFICE 文档服务之间交换命令时使用。密钥 用于签署 JSON Web Token 并在请求 ONLYOFFICE 文档 时验证令牌。

从 ONLYOFFICE 文档 v7.2 开始，JWT 默认启用，并自动生成密钥。您需要在 ONLYOFFICE 文档配置文件 中找到您的密钥，然后在连接器设置中指定相同的密钥。

步骤 1：在 ONLYOFFICE 文档配置文件 中找到您的密钥

1. 使用任何可用的文本编辑器打开 local.json 文件。
   • 对于 Linux - /etc/onlyoffice/documentserver/local.json
   • 对于 Windows - %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json
   • 对于 Docker – 使用 docker exec -it <containerID> bash 命令进入 ONLYOFFICE 文档容器并打开 /etc/onlyoffice/documentserver/local.json

     或者，您可以使用以下命令查找默认密钥，而无需打开 local.json：

     sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

   local.json 文件应如下所示：

   {"services": {"CoAuthoring": {"token": {"enable": {"request": {"inbox": true,"outbox": true},"browser": true}},"secret": {"inbox": {"string": "yoursecret"},"outbox": {"string": "yoursecret"},"session": {"string": "yoursecret"}}}}}

2. true 值指定在三个部分中。这意味着令牌验证已启用。
   • services.CoAuthoring.token.enable.browser
   • services.CoAuthoring.token.enable.request.inbox
   • services.CoAuthoring.token.enable.request.outbox
3. 自动生成的密钥在三个部分中指定。您可以用自己的密钥替换默认密钥。密钥在三个部分中必须相同。
   • services.CoAuthoring.secret.inbox.string
   • services.CoAuthoring.secret.outbox.string
   • services.CoAuthoring.secret.session.string
4. 如果您进行了更改，请保存并重新启动服务以使配置更改生效。

   supervisorctl restart all

步骤 2：在连接器设置中指定相同的密钥

在连接器设置中，在 密钥 字段中指定相同的密钥并保存设置。

连接到演示 ONLYOFFICE 文档

从 ONLYOFFICE 连接器版本 2.0.0 开始，您可以在 Jira 中尝试 ONLYOFFICE 在线编辑器，而无需安装 ONLYOFFICE 文档。

要打开连接，请勾选 连接到演示 ONLYOFFICE 文档服务器 复选框并点击 保存 按钮。