OpenProject 集成 XWiki企业版附加组件双向 OAuth 2.0 认证配置与环境变量部署实践【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openprojectOpenProject 通过 Wikis 模块将 XWiki 作为外部 Wiki 提供者接入使用双向 OAuth 2.0 授权码流程打通两边用户身份使工作包能够链接或创建 XWiki 页面。本篇基于系统管理员指南中的 XWiki 集成文档结合modules/wikis下的模型、契约、种子器与适配器源码完整讲清 XWiki 集成从插件安装、凭据配置、凭据轮换到环境变量批量配置的全部流程与底层机制。集成功能概览XWiki 集成是 OpenProject 的企业版附加组件feature flagxwiki_integration。围绕该功能官方文档给出了三个相互关联的主题主题说明Wiki 提供者配置总览OpenProject 中 Wiki 提供者Wiki provider配置的通用说明XWiki 提供者设置本文主体如何在 OpenProject 与 XWiki 两侧完成连接替换认证信息凭据丢失、泄露或需要轮换时的处理流程及其影响从源码结构看集成的核心模型是 Wikis::XWikiProvider它继承自通用的Provider并持有两个 OAuth 凭据对象has_one :oauth_client, as: :integration, dependent: :destroy has_one :oauth_application, class_name: ::Doorkeeper::Application, as: :integration, dependent: :destroy这两个关联恰好对应“双向”的含义oauth_client供 OpenProject 以 OAuth 客户端身份调用 XWikioauth_application基于 Doorkeeper 应用供 XWiki 反向调用 OpenProject。这也解释了后文为什么配置过程中会出现两对完全不同的 ID/Secret。前置条件重要设置此集成时你需要同时在 XWiki 和 OpenProject 两个实例中拥有管理员权限。第一步在 XWiki 中安装 OpenProject 插件以管理员身份打开 XWiki 实例点击右上角的Drawer图标选择Administer Wiki管理 Wiki。点击Extensions扩展搜索OpenProject Integration (Pro)并安装该插件。该插件是 XWiki 侧的对接方安装完成后 XWiki 才具备接收 OpenProject OAuth 客户端配置、并与 OpenProject 交换用户令牌的能力。第二步在 OpenProject 中创建 XWiki 提供者进入 OpenProject 管理设置页面在左侧菜单选择Wikis → Wiki providersWiki 提供者。点击 Wiki provider按钮并选择XWiki。页面标题变为New XWiki provider依次填写以下字段Name提供者名称。该名称会在从该 XWiki 实例链接页面到 OpenProject 时展示给用户Instance URLXWiki 实例地址。提交表单时 OpenProject 会主动校验该 URL 的可达性Authentication method认证方式决定 OpenProject 用户如何把账号关联到自己的 XWiki 账号。关于提交时的 URL 校验从源码结构看XWiki 适配器内置了分组的连接校验器 ConnectionValidator它基于HealthReports::Validator实现并设置了base_configuration分组先行通过后才执行认证分组检查的前置条件——即“先验证基本配置再验证认证链路”。第三步配置双向 OAuth 2.0 授权码流程目前 OpenProject 仅支持一种认证方式双向 OAuth 2.0 授权码流程Two-way OAuth 2.0 authorization code flow。该方式要求用户分别走完 OAuth 2.0 授权码流程把 OpenProject 账号关联到 XWiki 账号反之亦然。在模型层面可以印证这一点XWikiProvider 定义了认证方法常量其中oauth2_sso尚未实现AUTHENTICATION_METHODS [ AUTHENTICATION_METHOD_TWO_WAY_OAUTH2 two_way_oauth2 # AUTHENTICATION_METHOD_OAUTH2_SSO oauth2_sso # not yet implemented ].freeze3.1 录入 OpenProject 生成的应用凭据供 XWiki 调用进入该步骤后你会看到 OpenProject 生成的客户端凭据复制Application ID和Application secret粘贴到 XWiki 实例中对应的配置表单。表单上方会显示一个横幅banner其中包含指向 XWiki 正确配置页的链接。对应地OpenProject 侧为 XWiki 预建了一个 Doorkeeper 应用其client_id与client_secret就是此处展示的 Application ID / Application secret。3.2 录入 OpenProject 生成的 OAuth 客户端凭据供 OpenProject 调用 XWiki点击Done, continue进入下一步OpenProject 会生成Client ID和Client secret用于 XWiki 的 OAuth 客户端配置。注意生成的值仅为示例占位如有需要可以修改生成的 secret 满足安全强度的全部要求。复制包括Redirect URI在内的所有值粘贴到 XWiki 实例的对应表单表单上方同样会显示指向 XWiki 配置页的链接。关于自动生成凭据的安全强度可以直接从模型源码得到验证def generate_client_id openproject-#{SecureRandom.hex(8)} def generate_client_secret SecureRandom.alphanumeric(32)见 xwiki_provider.rb#L46-L50。3.3 保存并确认完成上述两侧录入后点击Save and continueXWiki 提供者的配置即告完成页面会跳转到该提供者的详情details页。模型中的configured?方法定义了“配置完成”的判定标准——url、oauth_client、oauth_application三者缺一不可def configured? url.present? oauth_client.present? oauth_application.present? end见 xwiki_provider.rb#L52-L56。替换认证信息凭据轮换当认证凭据丢失、泄露或需要重新生成时可以通过以下流程替换点击 XWiki 提供者的名称进入该提供者的详情页面在对应配置项旁点击Replace。替换动作对每一对凭据各自独立可用确认后才会生成新凭据。与“双向 OAuth 2.0 授权码流程”一节相同你需要把新值再次复制到 XWiki 侧对应的表单中。重要每次重置凭据后受影响一侧的所有用户都必须重新连接。例如替换 Wiki OAuth 凭据后OpenProject 账号到 XWiki 账号的关联会失效需要重新建立连接。从源码结构看这一行为符合 OAuth 客户端令牌与用户绑定关系的设计XWikiProvider 通过OAuthClients::TokenFetcher#connected?判断某个用户是否已建立连接凭据一旦更换旧令牌不再有效用户自然需要重新走一遍授权流程。配置完成后如需了解如何把 Wiki 页面链接到工作包或从工作包创建新页面请参考工作包编辑用户指南中的“Link to or create a wiki page”部分。使用环境变量配置提供者在某些部署场景下如基础设施即代码、容器化交付你可能希望通过环境变量来配置提供者。这些变量遵循OpenProject 环境变量使用规则。配置项OPENPROJECT_WIKI__PROVIDERS接受一个 JSON 对象数组用于配置 XWiki 等外部 Wiki 提供者。每个 XWiki 提供者可以定义以下属性属性说明type必须设为xwikiname对用户可见的 Wiki 提供者名称urlWiki 提供者的基础 URLuid可选对应 XWiki 实例的安装 id。未提供时会在后续异步获取openproject_oauthOpenProject 侧应用凭据容器openproject_oauth.client_idXWiki 用于向 OpenProject 进行 OAuth 认证的客户端 IDopenproject_oauth.client_secretXWiki 用于向 OpenProject 进行 OAuth 认证的客户端密钥务必选用强密码xwiki_oauthXWiki 侧客户端凭据容器xwiki_oauth.client_idOpenProject 用于向 XWiki 进行 OAuth 认证的客户端 IDxwiki_oauth.client_secretOpenProject 用于向 XWiki 进行 OAuth 认证的客户端密钥单提供者配置示例[{ type: xwiki, name: XWiki knowledge base, url: https://xwiki.example.com, openproject_oauth: { client_id: xwiki, client_secret: secret }, xwiki_oauth: { client_id: openproject, client_secret: secret } }]其中uid的“异步获取”特性在源码中同样有对应实现提供者创建后会由 FetchInstanceIdJob 等异步作业补取 XWiki 实例 id对应查询服务 queries/instance_id.rb。应用环境变量配置修改环境变量后需要运行db:seedrake 任务来应用配置。在标准安装流程中升级或安装应用时该命令会自动执行手动应用时可按安装方式选择以下命令软件包安装Packagedsudo openproject run bundle exec rake db:seedDockerdocker exec -it container of all-in-one or web bundle exec rake db:seed这一机制的实现位于种子器 EnvData::Wikis::ExternalProviderSeeder它遍历Setting.wiki_providers中的每一条 JSON 配置按type字段分派同步服务——type为xwiki时调用 Wikis::XWikiEnvSyncService 执行“创建或更新”遇到不支持的type会直接抛出Unsupported external wiki provider异常同步失败时种子任务也会以raise result.message中断并报错便于在 CI 或部署脚本中及时发现配置问题。此外db:seed对已存在的Wiki 提供者同样生效系统会优先用uid若已定义匹配否则回退到人类可读名称来匹配环境变量中声明的提供者从而完成更新而非重复创建。底层实现要点小结结合modules/wikis的源码结构可以概括 XWiki 集成在 OpenProject 内部的落地方式提供者模型Wikis::XWikiProvider 存储 URL、认证方式默认two_way_oauth2等选项并双向挂接 OAuth 客户端与应用管理契约Contractscreate_contract.rb、update_contract.rb 与专门的环境变量契约 environment_create_contract.rb、environment_update_contract.rb 分别约束管理界面与环境变量两条配置路径的入参API 适配层modules/wikis/app/services/wikis/adapters/providers/xwiki/queries/下提供了页面浏览browse_pages、搜索search_pages、页面层级与稳定引用canonical_page_hierarchy、stable_page_info等查询服务支撑“在工作包中链接/创建 XWiki 页面”的用户侧功能测试覆盖modules/wikis/spec/下对契约、服务、控制器均有对应测试如 create_service_spec.rb、wiki_providers_controller_spec.rb可结合 xwiki_stubs.rb 中的 XWiki API 桩了解两侧交互的接口形态。参考路径官方配置文档docs/system-admin-guide/integrations/xwiki/README.mdWiki 提供者通用配置docs/system-admin-guide/wikis/README.md环境变量规则docs/installation-and-operations/configuration/environment/README.md核心模型modules/wikis/app/models/wikis/xwiki_provider.rb环境变量同步种子器modules/wikis/app/seeders/env_data/wikis/external_provider_seeder.rb【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenProject 集成 XWiki（企业版附加组件）：双向 OAuth 2.0 认证配置与环境变量部署实践
OpenProject 集成 XWiki企业版附加组件双向 OAuth 2.0 认证配置与环境变量部署实践【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openprojectOpenProject 通过 Wikis 模块将 XWiki 作为外部 Wiki 提供者接入使用双向 OAuth 2.0 授权码流程打通两边用户身份使工作包能够链接或创建 XWiki 页面。本篇基于系统管理员指南中的 XWiki 集成文档结合modules/wikis下的模型、契约、种子器与适配器源码完整讲清 XWiki 集成从插件安装、凭据配置、凭据轮换到环境变量批量配置的全部流程与底层机制。集成功能概览XWiki 集成是 OpenProject 的企业版附加组件feature flagxwiki_integration。围绕该功能官方文档给出了三个相互关联的主题主题说明Wiki 提供者配置总览OpenProject 中 Wiki 提供者Wiki provider配置的通用说明XWiki 提供者设置本文主体如何在 OpenProject 与 XWiki 两侧完成连接替换认证信息凭据丢失、泄露或需要轮换时的处理流程及其影响从源码结构看集成的核心模型是 Wikis::XWikiProvider它继承自通用的Provider并持有两个 OAuth 凭据对象has_one :oauth_client, as: :integration, dependent: :destroy has_one :oauth_application, class_name: ::Doorkeeper::Application, as: :integration, dependent: :destroy这两个关联恰好对应“双向”的含义oauth_client供 OpenProject 以 OAuth 客户端身份调用 XWikioauth_application基于 Doorkeeper 应用供 XWiki 反向调用 OpenProject。这也解释了后文为什么配置过程中会出现两对完全不同的 ID/Secret。前置条件重要设置此集成时你需要同时在 XWiki 和 OpenProject 两个实例中拥有管理员权限。第一步在 XWiki 中安装 OpenProject 插件以管理员身份打开 XWiki 实例点击右上角的Drawer图标选择Administer Wiki管理 Wiki。点击Extensions扩展搜索OpenProject Integration (Pro)并安装该插件。该插件是 XWiki 侧的对接方安装完成后 XWiki 才具备接收 OpenProject OAuth 客户端配置、并与 OpenProject 交换用户令牌的能力。第二步在 OpenProject 中创建 XWiki 提供者进入 OpenProject 管理设置页面在左侧菜单选择Wikis → Wiki providersWiki 提供者。点击 Wiki provider按钮并选择XWiki。页面标题变为New XWiki provider依次填写以下字段Name提供者名称。该名称会在从该 XWiki 实例链接页面到 OpenProject 时展示给用户Instance URLXWiki 实例地址。提交表单时 OpenProject 会主动校验该 URL 的可达性Authentication method认证方式决定 OpenProject 用户如何把账号关联到自己的 XWiki 账号。关于提交时的 URL 校验从源码结构看XWiki 适配器内置了分组的连接校验器 ConnectionValidator它基于HealthReports::Validator实现并设置了base_configuration分组先行通过后才执行认证分组检查的前置条件——即“先验证基本配置再验证认证链路”。第三步配置双向 OAuth 2.0 授权码流程目前 OpenProject 仅支持一种认证方式双向 OAuth 2.0 授权码流程Two-way OAuth 2.0 authorization code flow。该方式要求用户分别走完 OAuth 2.0 授权码流程把 OpenProject 账号关联到 XWiki 账号反之亦然。在模型层面可以印证这一点XWikiProvider 定义了认证方法常量其中oauth2_sso尚未实现AUTHENTICATION_METHODS [ AUTHENTICATION_METHOD_TWO_WAY_OAUTH2 two_way_oauth2 # AUTHENTICATION_METHOD_OAUTH2_SSO oauth2_sso # not yet implemented ].freeze3.1 录入 OpenProject 生成的应用凭据供 XWiki 调用进入该步骤后你会看到 OpenProject 生成的客户端凭据复制Application ID和Application secret粘贴到 XWiki 实例中对应的配置表单。表单上方会显示一个横幅banner其中包含指向 XWiki 正确配置页的链接。对应地OpenProject 侧为 XWiki 预建了一个 Doorkeeper 应用其client_id与client_secret就是此处展示的 Application ID / Application secret。3.2 录入 OpenProject 生成的 OAuth 客户端凭据供 OpenProject 调用 XWiki点击Done, continue进入下一步OpenProject 会生成Client ID和Client secret用于 XWiki 的 OAuth 客户端配置。注意生成的值仅为示例占位如有需要可以修改生成的 secret 满足安全强度的全部要求。复制包括Redirect URI在内的所有值粘贴到 XWiki 实例的对应表单表单上方同样会显示指向 XWiki 配置页的链接。关于自动生成凭据的安全强度可以直接从模型源码得到验证def generate_client_id openproject-#{SecureRandom.hex(8)} def generate_client_secret SecureRandom.alphanumeric(32)见 xwiki_provider.rb#L46-L50。3.3 保存并确认完成上述两侧录入后点击Save and continueXWiki 提供者的配置即告完成页面会跳转到该提供者的详情details页。模型中的configured?方法定义了“配置完成”的判定标准——url、oauth_client、oauth_application三者缺一不可def configured? url.present? oauth_client.present? oauth_application.present? end见 xwiki_provider.rb#L52-L56。替换认证信息凭据轮换当认证凭据丢失、泄露或需要重新生成时可以通过以下流程替换点击 XWiki 提供者的名称进入该提供者的详情页面在对应配置项旁点击Replace。替换动作对每一对凭据各自独立可用确认后才会生成新凭据。与“双向 OAuth 2.0 授权码流程”一节相同你需要把新值再次复制到 XWiki 侧对应的表单中。重要每次重置凭据后受影响一侧的所有用户都必须重新连接。例如替换 Wiki OAuth 凭据后OpenProject 账号到 XWiki 账号的关联会失效需要重新建立连接。从源码结构看这一行为符合 OAuth 客户端令牌与用户绑定关系的设计XWikiProvider 通过OAuthClients::TokenFetcher#connected?判断某个用户是否已建立连接凭据一旦更换旧令牌不再有效用户自然需要重新走一遍授权流程。配置完成后如需了解如何把 Wiki 页面链接到工作包或从工作包创建新页面请参考工作包编辑用户指南中的“Link to or create a wiki page”部分。使用环境变量配置提供者在某些部署场景下如基础设施即代码、容器化交付你可能希望通过环境变量来配置提供者。这些变量遵循OpenProject 环境变量使用规则。配置项OPENPROJECT_WIKI__PROVIDERS接受一个 JSON 对象数组用于配置 XWiki 等外部 Wiki 提供者。每个 XWiki 提供者可以定义以下属性属性说明type必须设为xwikiname对用户可见的 Wiki 提供者名称urlWiki 提供者的基础 URLuid可选对应 XWiki 实例的安装 id。未提供时会在后续异步获取openproject_oauthOpenProject 侧应用凭据容器openproject_oauth.client_idXWiki 用于向 OpenProject 进行 OAuth 认证的客户端 IDopenproject_oauth.client_secretXWiki 用于向 OpenProject 进行 OAuth 认证的客户端密钥务必选用强密码xwiki_oauthXWiki 侧客户端凭据容器xwiki_oauth.client_idOpenProject 用于向 XWiki 进行 OAuth 认证的客户端 IDxwiki_oauth.client_secretOpenProject 用于向 XWiki 进行 OAuth 认证的客户端密钥单提供者配置示例[{ type: xwiki, name: XWiki knowledge base, url: https://xwiki.example.com, openproject_oauth: { client_id: xwiki, client_secret: secret }, xwiki_oauth: { client_id: openproject, client_secret: secret } }]其中uid的“异步获取”特性在源码中同样有对应实现提供者创建后会由 FetchInstanceIdJob 等异步作业补取 XWiki 实例 id对应查询服务 queries/instance_id.rb。应用环境变量配置修改环境变量后需要运行db:seedrake 任务来应用配置。在标准安装流程中升级或安装应用时该命令会自动执行手动应用时可按安装方式选择以下命令软件包安装Packagedsudo openproject run bundle exec rake db:seedDockerdocker exec -it container of all-in-one or web bundle exec rake db:seed这一机制的实现位于种子器 EnvData::Wikis::ExternalProviderSeeder它遍历Setting.wiki_providers中的每一条 JSON 配置按type字段分派同步服务——type为xwiki时调用 Wikis::XWikiEnvSyncService 执行“创建或更新”遇到不支持的type会直接抛出Unsupported external wiki provider异常同步失败时种子任务也会以raise result.message中断并报错便于在 CI 或部署脚本中及时发现配置问题。此外db:seed对已存在的Wiki 提供者同样生效系统会优先用uid若已定义匹配否则回退到人类可读名称来匹配环境变量中声明的提供者从而完成更新而非重复创建。底层实现要点小结结合modules/wikis的源码结构可以概括 XWiki 集成在 OpenProject 内部的落地方式提供者模型Wikis::XWikiProvider 存储 URL、认证方式默认two_way_oauth2等选项并双向挂接 OAuth 客户端与应用管理契约Contractscreate_contract.rb、update_contract.rb 与专门的环境变量契约 environment_create_contract.rb、environment_update_contract.rb 分别约束管理界面与环境变量两条配置路径的入参API 适配层modules/wikis/app/services/wikis/adapters/providers/xwiki/queries/下提供了页面浏览browse_pages、搜索search_pages、页面层级与稳定引用canonical_page_hierarchy、stable_page_info等查询服务支撑“在工作包中链接/创建 XWiki 页面”的用户侧功能测试覆盖modules/wikis/spec/下对契约、服务、控制器均有对应测试如 create_service_spec.rb、wiki_providers_controller_spec.rb可结合 xwiki_stubs.rb 中的 XWiki API 桩了解两侧交互的接口形态。参考路径官方配置文档docs/system-admin-guide/integrations/xwiki/README.mdWiki 提供者通用配置docs/system-admin-guide/wikis/README.md环境变量规则docs/installation-and-operations/configuration/environment/README.md核心模型modules/wikis/app/models/wikis/xwiki_provider.rb环境变量同步种子器modules/wikis/app/seeders/env_data/wikis/external_provider_seeder.rb【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考