Jira

关于 ONLYOFFICE 与 Jira 集成

ONLYOFFICE 提供官方连接器，可将 ONLYOFFICE Docs 与 Jira 集成，以便协作处理附加在 Jira 问题上的办公文档。根据您的 Jira 部署方式，提供两种连接器：

• Jira Data Center / Server — 可在 Atlassian Marketplace 和 GitHub 上获取。采用 Apache 许可证分发。
• Jira Cloud — 可在 Atlassian Marketplace 和 GitHub 上获取。采用 Apache 许可证分发。

备注

要详细了解 Jira 连接器的工作原理，请访问我们的 API 文档。

主要功能

• 创建新的文档、电子表格、演示文稿和表单。

• 使用 Edit in ONLYOFFICE（在 ONLYOFFICE 中编辑）选项查看和编辑文本文档、电子表格、演示文稿和表单。

  备注

  要详细了解表单，请阅读有关创建和填写表单的相应文章。

• 实时共同编辑文档：两种共同编辑模式（快速和严格）、修订、批注和内置聊天。

• JWT 支持，保护您的流量安全，除具有适当权限的用户外，任何人都无法访问您的文档。

• AI 助手支持（仅限 Jira Cloud）— 通过 AI 插件连接您偏好的 AI 提供商。兼容 OpenAI、Mistral、Anthropic、Google Gemini、DeepSeek 等。有关详细信息，请参阅 AI 指南。

支持的格式

用于查看：

• WORD：DOC、DOCM、DOCX、DOT、DOTM、DOTX、EPUB、FB2、FODT、HTM、HTML、HWP、HWPX、MD、MHT、MHTML、ODT、OTT、PAGES、RTF、STW、SXW、TXT、WPS、WPT、XML
• CELL：CSV、ET、ETT、FODS、NUMBERS、ODS、OTS、SXC、XLS、XLSM、XLSX、XLT、XLTM、XLTX
• SLIDE：DPS、DPT、FODP、KEY、ODG、ODP、OTP、POT、POTM、POTX、PPS、PPSM、PPSX、PPT、PPTM、PPTX、SXI
• PDF：DJVU、DOCXF、OFORM、OXPS、PDF、XPS
• DIAGRAM：VSDM、VSDX、VSSM、VSSX、VSTM、VSTX

用于编辑：

• WORD：DOCM、DOCX、DOTM、DOTX
• CELL：XLSB、XLSM、XLSX、XLTM、XLTX
• SLIDE：POTM、POTX、PPSM、PPSX、PPTM、PPTX
• PDF：PDF

在 Jira Data Center / Server 中，以下格式也可用于编辑。请注意，编辑这些格式可能会导致信息丢失：

• WORD：EPUB、FB2、HTML、ODT、OTT、RTF、TXT
• CELL：CSV、ODS、OTS
• SLIDE：ODP、OTP

4.1.1 版本的新增内容

Jira Data Center

更改

• 修复了在使用上下文路径部署 Jira 时插件 HTTP 请求的问题。

完整的更新日志请见此处。

Jira Cloud

新增

• ONLYOFFICE Jira Cloud 连接器的初始版本。

完整的更新日志请见此处。

将 ONLYOFFICE Docs 连接到 Jira Data Center / Server

要求

• ONLYOFFICE Document Server v6.4.0 或更高版本（服务器版或云版）。

  您需要一个 ONLYOFFICE Docs 实例，该实例必须能够被 Jira 和所有终端客户端解析并连接。它必须能够直接向 Jira 发送 POST 请求。

  备注

  要详细了解如何安装 ONLYOFFICE Docs，请参阅官方文档页面。

• Jira Software. 针对不同的 Jira Data Center 版本有两种连接器：

  • 适用于 Jira Software（Server 或 Data Center）v. 9.0.0 — 9.17.5 的 ONLYOFFICE 连接器 v3.1.1
  • 适用于 Jira Software（Server 或 Data Center）v. 10.0.0 — 10.7.2 的 ONLYOFFICE 连接器 v4.1.1
  备注

  要详细了解如何安装 Jira Software，请参阅官方 Atlassian 文档。

• 适用于 Jira 的 ONLYOFFICE 连接器。

  请参阅此列表下载所需的连接器版本。

安装适用于 Jira 的 ONLYOFFICE 连接器

您可以从官方 Atlassian Marketplace 下载连接器，也可以使用 GitHub 上提供的源代码自行编译。

从 Atlassian Marketplace 添加连接器

• 以管理员身份登录您的 Jira Software 实例。

• 点击右上角的 Administration（管理）图标，然后从菜单中选择 Manage apps（管理应用）选项。

  

• 将打开 Find new apps（查找新应用）部分。点击 Search the Marketplace（搜索 Marketplace）字段，找到 Jira ONLYOFFICE integration app。

• 点击 Install（安装）按钮下载并安装该应用程序。

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

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

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

要编译适用于 Jira 的 ONLYOFFICE 连接器，请按以下步骤操作：

• 克隆 onlyoffice-jira 仓库。

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

• 进入 onlyoffice-jira 目录。

  cd onlyoffice-jira

• 运行以下命令：

  atlas-package

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

您可以在 Jira Software Administration > Manage Apps 页面上传编译好的连接器。

• 以管理员身份登录您的 Jira Software 实例。

• 点击右上角的 Administration（管理）图标，然后从菜单中选择 Manage apps（管理应用）选项。

• 在页面左侧选择 Manage apps 部分。

• 点击 Upload app（上传应用）链接。

• 点击 Choose File（选择文件）按钮，浏览并选择编译好的 target/onlyoffice-jira-app.jar 文件，然后点击 Upload（上传）。请等待应用程序安装完成。

  

配置适用于 Jira 的 ONLYOFFICE 连接器

在 Manage apps 页面上，点击已安装的 Jira ONLYOFFICE integration app 下方的 Configure（配置）按钮，或在 Manage apps 页面的 OTHER 部分找到该应用。

Document Server

1. 在 Document Editing Service address（文档编辑服务地址）字段中，指定安装了 ONLYOFFICE Docs 的服务器的 IP 地址或主机名。

   备注

   ONLYOFFICE Docs 的地址必须可从 Jira 访问，同样，Jira 的地址也必须可从 ONLYOFFICE Docs 访问。

2. Disable certificate verification (insecure)（禁用证书验证（不安全））— 如果您使用自签名证书，请选中此框以禁用证书验证，并允许 Jira 与 ONLYOFFICE Docs 建立连接。这是一种不安全的解决方案；我们强烈建议将证书替换为由 CA 颁发的证书。

3. 指定 Secret key（密钥）（留空则禁用）— 在向 ONLYOFFICE Docs 发出请求时用于验证 JSON Web 令牌的密钥。

   备注

   从 ONLYOFFICE Docs v7.2 开始，JWT 默认启用，并自动生成密钥。您还需要在 Jira 端启用它：在 ONLYOFFICE Docs 配置文件中找到您的密钥，然后在连接器设置中指定相同的密钥。有关更多详细信息，请参阅本文的启用 JWT部分。

4. Authorization header（授权标头）（留空则使用默认标头）— ONLYOFFICE 中使用的授权 JWT 标头为 Authorization。如果该标头与您的设置冲突，可以将其更改为自定义标头。

5. Connect to demo ONLYOFFICE Document Server（连接到 ONLYOFFICE Document Server 演示版）— 启动测试服务器。

   重要

   这是一个公共测试服务器，可使用 30 天。请勿在其上共享敏感数据。

Advanced server settings（高级服务器设置）

如果您的网络配置不允许 Jira Software 与 ONLYOFFICE Docs 之间使用公共地址进行请求，可以使用 Advanced server settings 部分。请在相应字段中指定内部请求的地址：

1. Server address for internal requests from the Document Editing Service（来自文档编辑服务的内部请求的服务器地址）— 来自 ONLYOFFICE Docs 的内部请求所使用的 Jira Software 服务器地址。
2. Document Editing Service address for internal requests from the server（来自服务器的内部请求的文档编辑服务地址）— 来自 Jira Software 服务器的内部请求所使用的 ONLYOFFICE Docs 地址。

Common settings（常规设置）

1. Editable formats（可编辑格式）— 选中您的 Jira 环境所支持的格式旁边的复选框。

   由于格式限制，以指定格式保存时可能会发生数据丢失。

2. Editor interface（编辑器界面）— 自定义编辑器的界面：

   • Display Chat menu button — 隐藏/显示左侧面板上的在线内置 Chat（聊天）图标。
   • Display the header more compact — 隐藏/显示顶部工具栏上的图标文字。
   • Display Feedback & Support menu button — 隐藏/显示左侧面板上的 Feedback & Support（反馈与支持）按钮。
   • Display Help menu button — 隐藏/显示左侧面板上的 Help（帮助）按钮。
   • Display monochrome toolbar header — 将顶部工具栏切换为单色调色板。

Security（安全）

1. Enable plugins — 启用/禁用编辑器的插件支持。
2. Run document macros — 启用/禁用在编辑器中运行宏。
3. Enable document protection for — 选择是允许所有用户还是仅允许文档所有者为文档启用密码保护。

点击 Save（保存）保存设置。

工作原理

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

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

启用 JWT

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

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

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

1. 使用任意可用的文本编辑器打开 local.json 文件：

   • Linux — /etc/onlyoffice/documentserver/local.json

   • Windows — %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json

   • Docker — 使用 docker exec -it <containerID> bash 命令进入 ONLYOFFICE Docs 容器，然后打开 /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：在连接器设置中指定相同的密钥

在连接器设置的 Secret key（密钥）字段中指定相同的密钥，然后保存设置。

连接到 ONLYOFFICE Docs 演示版

从 ONLYOFFICE 连接器 2.0.0 版本开始，您无需安装 ONLYOFFICE Docs，即可在 Jira 中试用 ONLYOFFICE 在线编辑器。

要启用连接，请选中 Connect to demo ONLYOFFICE Docs server 复选框，然后点击 Save（保存）按钮。

重要

这是一个公共测试服务器，可使用 30 天。请勿在其上共享敏感数据。

将 ONLYOFFICE Docs 连接到 Jira Cloud

要求

• 一个 ONLYOFFICE Docs 实例 — 自托管或云均可。
• Jira Cloud。
• 来自 Atlassian Marketplace 的适用于 Jira Cloud 的 ONLYOFFICE 连接器。

安装适用于 Jira Cloud 的 ONLYOFFICE 连接器

• 访问 marketplace.atlassian.com。
• 找到 ONLYOFFICE Connector for Jira，然后点击 Get it now（立即获取）按钮。
• 在弹出窗口中，选择要安装该应用的站点；如果有多个版本可选，请选择版本。

配置适用于 Jira Cloud 的 ONLYOFFICE 连接器

管理员可以通过 Apps → Manage apps → ONLYOFFICE Connector for Jira → Configure 配置 ONLYOFFICE 应用。在配置页面上设置：

• ONLYOFFICE Docs address（ONLYOFFICE Docs 地址）— 已安装的 ONLYOFFICE Docs 的 URL。
• ONLYOFFICE Docs secret key（ONLYOFFICE Docs 密钥）— 启用 JWT，保护您的文档免受未经授权的访问。有关详细信息，请参阅 JWT 配置指南。
• Authorization header（授权标头）。

您还可以通过选中相应的复选框，连接到 ONLYOFFICE Docs 公共测试服务器，使用期限为一个月。

重要

这是一个公共测试服务器，可使用 30 天。请勿在其上共享敏感数据。

开始在 Jira Data Center / Server 中使用 ONLYOFFICE Docs

创建、查看和编辑文件

您可以从问题的任何 Attachments（附件）区域打开 ONLYOFFICE 编辑器。此选项适用于任何可打开问题的模块中的问题，例如问题列表、待办事项列表等。

备注

附件必须由管理员启用。

可以在问题页面上使用 More → Attach files（更多 → 附加文件）选项添加新附件。要了解更多信息，请参阅官方文档。

要打开现有的文本文档、电子表格、演示文稿或表单，请将鼠标指针移到所需文件上，然后点击 Edit in ONLYOFFICE 图标。如果文件格式不支持编辑，则可使用 View in ONLYOFFICE（在 ONLYOFFICE 中查看）选项。对于 .oform 文件，可使用 Fill in form in ONLYOFFICE（在 ONLYOFFICE 中填写表单）选项。生成的文档将以 PDF 格式保存。

文件将在新的浏览器标签页中的相应 ONLYOFFICE 编辑器中打开。

要使用 ONLYOFFICE 编辑器创建新文件：

• 在问题的 Attachments 区域中，点击 Create file with ONLYOFFICE（使用 ONLYOFFICE 创建文件）选项。

• 选择所需的文件类型：文档、电子表格、演示文稿或表单模板。

• 输入文件名，然后点击 Create（创建）。

  

• 文件将在新的浏览器标签页中的相应 ONLYOFFICE 编辑器中打开。

编辑会话结束后，包含所有更改的文档将保存为新附件。您可以通过带后缀的同名文件来识别它。如果您正在协作编辑某个附件，只有在最后一位用户退出编辑器后才会保存更改。

访问权限

文件的访问权限取决于用户对相应问题的访问权限。

编辑文件。要能够编辑文件，用户必须具有创建附件的权限（Create attachments）。

查看文件。所有可以查看问题、但没有编辑问题的权限也没有创建附件权限的用户，都可以在 ONLYOFFICE 查看器中预览文件。如果文件格式不支持编辑，则文件将以查看模式打开。

转换文档

要将文档转换为 Office Open XML 格式：

• 将鼠标指针移到所需文件上，然后点击 ONLYOFFICE conversion service（ONLYOFFICE 转换服务）图标。

  

• 您可以选择更改文件名。

• 点击 Convert（转换）按钮。

• 转换后的文件将存储在 Attachments 区域中。

  

保存更改

对文件所做的更改将保存到一个新文件中，该文件与原始文件同名，但文件名末尾添加了后缀，例如 Sample-1.docx。

共同编辑过程中对文件所做的更改仅保存到文件的第一个版本。如果多位用户同时编辑文档，则更改只会显示在第一个文件中。在最后一位用户关闭编辑器之前，不会向问题添加文件的新版本。

下载文件

要以其他格式下载文档：

• 将鼠标指针移到所需文件上，然后点击 ONLYOFFICE conversion service（ONLYOFFICE 转换服务）图标。

  

• 您可以选择更改文件名。

• 从 Target type（目标类型）列表中选择所需的格式。

• 点击 Download（下载）按钮。

• 下载的文件将存储在您的计算机上。

备注

要详细了解最常见的问题及其解决方法，请访问我们的故障排除指南。

开始在 Jira Cloud 中使用 ONLYOFFICE Docs

Jira 问题页面包含一个 ONLYOFFICE Docs 部分。如果没有看到，请点击问题标题下方的齿轮图标，然后选择 ONLYOFFICE Docs 将其启用。

创建文件

要创建新文件，请点击 Create with ONLYOFFICE（使用 ONLYOFFICE 创建）按钮。在弹出窗口中，输入文件名并选择文件格式。目前，您可以创建 DOCX、XLSX、PPTX 和 PDF 表单格式的文件。

点击 Create（创建）后，文件将被生成并立即在具有编辑权限的弹出窗口中打开。新创建的文件也会添加到 Attachments 部分。

编辑和查看文件

要打开现有文件进行编辑，请点击其旁边的铅笔图标。要仅以查看模式打开，请点击眼睛图标。编辑器将相应启动。

重要

由于连接器的限制，编辑器无法长时间保持打开状态。必须每四小时重新启动一次，以确保其正常运行。

访问权限

• 下载和查看：所有有权访问该 Jira 问题的用户都可以使用。
• 编辑：用户可以编辑自己创建的文件。要编辑他人创建的文件，用户必须具有 Delete All Attachments 权限。

要向特定的 Jira 角色授予编辑权限：

• 打开所需项目的上下文菜单，然后选择 Project settings（项目设置）。
• 转到 Permissions（权限）部分，点击 Action（操作）按钮，并更新 Delete All Attachments 的角色列表。