Potpie 外部集成模块 potpie-integrations 深入解析六边形架构下的 OAuth 提供方、Project Sources 与 HTTP 路由【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读potpie-integrations是 Potpie 中负责对接外部服务的集成层覆盖 OAuth 提供方Sentry、Linear、Jira、Confluence、project_sources项目源管理、Linear 同步与 HTTP 路由。本文以 potpie/integrations/README.md 为骨架结合该模块源码逐层拆解其六边形架构、Provider 注册机制、OAuth 授权码交换与加密存储流程、以及/integrations与/sources两套 FastAPI 路由的实现细节。读完本文你将掌握如何在 Potpie 中接入一个新的 OAuth 集成、如何通过project_sources将外部数据源挂载到项目以及这套镜像context-engine的模块布局为什么能避免与主工程的可编辑安装冲突。一、模块定位Potpie 的对外集成层按照 README 的定义potpie-integrations承担四类职责OAuth providers实现 Sentry、Linear、Jira、Confluence 等第三方服务的 OAuth 授权码流程project_sources管理某个 Potpie 项目与外部数据源如 GitHub 仓库、Linear 团队的挂载关系Linear sync通过 Linear GraphQL 客户端按需读取组织、团队数据HTTP routers以 FastAPI 路由的形式暴露给主应用挂载供前端调用。与context-engine类似该模块采用**六边形架构端口与适配器**组织代码四个核心目录各司其职目录职责代表文件integrations/domain/注册表、Provider 定义、共享 Schemaprovider_registry.py、provider_definitions.py、integrations_schema.pyintegrations/application/服务编排、Provider 引导integrations_service.py、project_sources_service.py、bootstrap.pyintegrations/adapters/outbound/持久化模型、OAuth 客户端、Linear GraphQL、加密postgres/、oauth/、linear/、crypto/、providers/integrations/adapters/inbound/http/被主应用挂载的 FastAPI 路由integrations_router.py、sources_router.py一个值得注意的设计决策是可安装的 Python 包根目录是integrations而不是顶层的domain/application。这一点在 pyproject.toml 中体现为[build-system] requires [hatchling] build-backend hatchling.build [project] name potpie-integrations version 0.1.0 requires-python 3.12,3.15 dependencies [] [tool.hatch.build.targets.wheel] packages [integrations]由于 wheel 只打包integrations一个顶层包它不会与context-engine的可编辑安装editable install产生顶层命名空间碰撞两个子系统可以在同一进程中安全共存。README 明确给出了这一动机布局刻意镜像context-enginehexagonal。二、Domain 层Provider 注册表与共享 Schema2.1 ProviderDefinition一个 Provider 的目录条目provider_definitions.py 定义了ProviderDefinition它是一个 frozen dataclass用于描述某个外部服务在 Potpie 中扮演什么角色PortKind Literal[source_control, issue_tracker] dataclass(frozenTrue, slotsTrue) class ProviderDefinition: id: str display_name: str capabilities: tuple[str, ...] # 如 (code_host,) 或 (issue_tracker,) source_kinds: tuple[str, ...] # 如 (repository,) 或 (issue_tracker_team,) port_kind: PortKind # 实现的是 SCM 端口还是 issue tracker 端口 oss_available: bool True字段语义capabilities该提供方具备的能力标签例如 GitHub 是code_hostLinear 是issue_trackersource_kinds该提供方支持的挂载类型例如 GitHub 支持repositoryLinear 支持issue_tracker_teamport_kind标识其实现的是哪个领域端口——source_control源代码托管还是issue_tracker问题跟踪。2.2 ProviderRegistry进程内注册表provider_registry.py 实现了一个进程内单例注册表提供注册、查询、列举能力class ProviderRegistry: def __init__(self) - None: self._by_id: dict[str, ProviderDefinition] {} def register(self, definition: ProviderDefinition) - None: if definition.id in self._by_id: raise ValueError(fProvider already registered: {definition.id!r}) self._by_id[definition.id] definition def get(self, provider_id: str) - ProviderDefinition | None: return self._by_id.get(provider_id) def list_all(self) - list[ProviderDefinition]: return sorted(self._by_id.values(), keylambda d: d.display_name.lower())通过get_provider_registry()惰性创建单例reset_provider_registry_for_tests()供测试隔离使用。注意register()对重复 id 直接抛出ValueError避免目录条目被意外覆盖。仓库当前注册了两个 OSS Provider分别在 adapters/outbound/providers/github.py 与 linear.py 中# github.py registry.register(ProviderDefinition( idgithub, display_nameGitHub, capabilities(code_host,), source_kinds(repository,), port_kindsource_control, oss_availableTrue, )) # linear.py registry.register(ProviderDefinition( idlinear, display_nameLinear, capabilities(issue_tracker,), source_kinds(issue_tracker_team,), port_kindissue_tracker, oss_availableTrue, ))也就是说OSS 版本开箱即拥有一个代码托管提供方GitHub和一个问题跟踪提供方Linear二者分别映射到source_control与issue_tracker两个领域端口。2.3 共享 Schema集成数据模型integrations_schema.py 使用 Pydantic 定义了完整的集成数据契约核心模型如下IntegrationType集成类型枚举支持sentry、github、slack、jira、linear、confluenceIntegrationStatus状态枚举取值active、inactive、pending、errorAuthData认证数据含access_token、refresh_token、token_type默认Bearer、expires_at、scope、codeScopeData作用域数据含org_slug、installation_id、workspace_id、project_idIntegrationMetadata元数据含instance_name、created_via默认oauth_callback、version、description、tagsIntegration核心集成模型聚合integration_id、name、integration_type、status、active、auth_data、scope_data、metadata、unique_identifier、created_by、created_at、updated_at。请求/响应包装模型包括IntegrationCreateRequest、IntegrationUpdateRequest当前仅允许修改name长度限制 1255、IntegrationResponse、IntegrationListResponse返回integrations字典以及按服务商细分的SentrySaveRequest/LinearSaveRequest/JiraSaveRequest/ConfluenceSaveRequest与对应的*SaveResponse。OAuth 侧还有OAuthInitiateRequestredirect_uri 可选state、OAuthCallbackRequest、OAuthTokenResponse、OAuthStatusResponse。值得留意的是通用保存模型IntegrationSaveRequest除name与integration_type必填外status、active、auth_data、scope_data、metadata都有默认值unique_identifier缺省时自动生成f{integration_type.value}-{integration_id}这为手动创建集成提供了最简入口。2.4 领域异常预期流程而非错误exceptions.py 定义了LinearOrganizationAlreadyIntegratedError其语义是OAuth 完成后发现该 Linear 组织已有集成记录。异常携带既有integration_id提示用户先删除旧集成再重连。服务层捕获后会原样上抛except LinearOrganizationAlreadyIntegratedError: raise路由层则据此跳转前端并标记already_existstrue属于预期流程而非程序错误。三、Application 层服务编排与 Provider 引导3.1 bootstrap.load_providers幂等引导 可选商业插件bootstrap.py 提供进程级的一次性引导同时被 API 进程与 Celery worker 调用def load_providers() - None: global _loaded if _loaded: return registry get_provider_registry() register_github_provider(registry) register_linear_provider(registry) _try_register_commercial(registry) _loaded True其关键机制幂等_loaded标志确保只注册一次reset_load_providers_for_tests()供测试重置可扩展_try_register_commercial()尝试导入potpie_integrations_commercial若导入成功且存在register_providers可调用对象则把商业插件提供的 Provider 一并注册导入失败静默返回。这意味着 Provider 目录可以在不修改 OSS 代码的前提下通过独立包扩展。3.2 IntegrationsServiceOAuth 编排核心integrations_service.py 是模块体量最大的服务类约 2800 行构造时通过Config()实例化四个 OAuth 客户端def __init__(self, db: Session): self.db db self.config Config() self.sentry_oauth SentryOAuthV2(self.config) self.linear_oauth LinearOAuth(self.config) self.jira_oauth JiraOAuth(self.config) self.confluence_oauth ConfluenceOAuth(self.config)授权码交换与加密存储以 Sentry 为例save_sentry_integration()完整演示了前端拿 code → 后端交换 → 加密入库的流程参数校验code长度不小于 20redirect_uri必填时效校验解析请求中的timestamp与当前 UTC 时间对比超过600 秒10 分钟判定授权码可能过期并拒绝OAuth 授权码典型有效期Token 交换调用self.sentry_oauth.exchange_code_for_tokens(code, redirect_uri)以application/x-www-form-urlencoded向https://sentry.io/oauth/token/提交grant_typeauthorization_code、client_id、client_secret、code、redirect_uri组织信息拉取交换成功后用 access token 调用https://sentry.io/api/0/organizations/取回第一个组织Sentry OAuth 通常只授权一个组织得到slug/name重复检查以{org_slug}-{user_id}作为unique_identifier查询是否已集成已存在则报错加密入库access/refresh token 经encrypt_token()加密后写入auth_datacode置为None交换后不保留授权码scope_data.org_slug记录组织 slugmetadata.created_viaoauth最终通过 SQLAlchemy 模型持久化到 PostgreSQL。Token 刷新与按需取用refresh_sentry_token(integration_id)实现了 token 过期后的自动刷新从数据库读取集成记录 → 校验类型为 sentry →decrypt_token()解密 refresh token → 用grant_typerefresh_token请求刷新端点 → 解析expires_in计算新过期时间 → 新 token 再次加密回写数据库。错误处理上做了敏感信息剥离错误级别日志只记录状态码与截断后的error/error_description前 200 字符完整响应体仅以 debug 级别记录避免泄露 token 或敏感上下文。get_valid_sentry_token(integration_id)则是业务侧的取用入口解密 access token若expires_at已过则先刷新再返回明文 token供后续 Sentry API 调用如make_sentry_api_call→/organizations/、/projects/、/issues/等端点使用。Linear 集成无 refresh token 的差异化处理save_linear_integration()与 Sentry 流程类似但有两点差异交换成功后额外调用get_user_info_from_api()获取用户与组织信息unique_identifier使用 Linear 的org_id缺省回退为linear-{urlKey}按代码注释Linear doesnt provide refresh tokens in basic OAuthAuthData.refresh_token显式置为None重复组织集成时抛出LinearOrganizationAlreadyIntegratedError并携带既有集成 ID。get_linear_integration_status()采用DB 优先、内存兜底的策略先查Integration表中该用户 active 的 linear 记录解析expires_at兼容字符串、datetime、时间戳三种格式查不到再回退到linear_oauth.get_user_info()的 legacy 内存数据。revoke_linear_integration()除了将集成行置为INACTIVE、清空 token 外还会把关联的ProjectSource标记为sync_enabledFalse并写入last_errorconnection revoked做到级联失效。通用 CRUD 与审计create_integration/update_integration/delete_integration_schema/list_integrations_schema提供基于 Schema 的完整 CRUD支持按integration_type、status、active、user_id过滤删除/更新/状态变更操作均通过结构化 logger 记录审计轨迹integration_id、name、type、created_by、created_at 等delete_integration对 Jira 集成会先调用_cleanup_jira_webhooks()删除已注册的 webhook从metadata.webhooks读取 webhook id解密 access token 后逐条调用jira_oauth.delete_webhook且清理失败不阻断删除日志兜底validate_oauth_configuration()可诊断SENTRY_CLIENT_ID、SENTRY_CLIENT_SECRET、SENTRY_REDIRECT_URI是否配置、长度是否过短、URI 是否为合法 URL便于快速排障。3.3 ProjectSourcesService项目源管理与幂等挂载project_sources_service.py 管理project_sources的增删查与同步状态。核心设计是基于 scope 哈希的幂等去重def compute_scope_hash(scope: dict[str, Any]) - str: return hashlib.sha256( json.dumps(scope, sort_keysTrue, defaultstr).encode(utf-8) ).hexdigest()关键函数ensure_github_repository_source(db, project_id, repo_name)以{repo_name: ...}的 scope 哈希判重若不存在则创建一行providergithub、source_kindrepository、sync_modehybrid、webhook_statusnot_applicable、health_score100的记录并发下通过捕获IntegrityError回滚后重查实现幂等attach_linear_team_source(db, ...)挂载 Linear 团队到项目。先校验项目归属Project.id project_id and Project.user_id user_id再校验集成归属与激活状态created_by user_id、integration_type linear、active True随后仅对{team_id: ...}计算去重哈希刻意忽略可变展示字段team_name新建行source_kindissue_tracker_team、webhook_statuspending_setuptouch_source_sync()同步健康度维护——出错时health_score减 10下限 0成功时加 5上限 100同时记录last_sync_at与last_errorget_project_source/list_all_sources_for_project/delete_project_source均以项目属于该用户为前提做归属过滤防止越权。四、Adapter 层OAuth 客户端、持久化模型与加密4.1 outbound 适配器全景integrations/adapters/outbound/按职责划分子目录内容oauth/atlassian_oauth_base.py、confluence_oauth.py、jira_oauth.py、linear_oauth.py、sentry_oauth_v2.pypostgres/integration_model.pyIntegration 表模型、project_source_model.pyProjectSource 表模型linear/adapter.py、graphql_client.pylinear_graphql(token, query, variables)客户端crypto/token_encryption.pyencrypt_token/decrypt_tokenproviders/github.py、linear.pyProvider 目录注册4.2 Token 加密边界所有持久化到auth_data的 access/refresh token 都先经过encrypt_token()加密读取时再用decrypt_token()解密。这一边界贯穿 service 层保存、刷新、API 调用与 sources 路由/sources/linear/teams中解密 Linear access token 后发起 GraphQL 查询确保数据库落盘的不是明文凭证。4.3 Linear 按需读取live query从 sources_router.py 可见Linear 团队列表是通过 GraphQL 实时查询获取的query Teams { viewer { organization { teams { nodes { id name key } } } } }路由先用AuthData.model_validate(row.auth_data)校验 token 存在再decrypt_token()解密后交给linear_graphql执行。注意代码注释明确写着Linear ETL was removed; linear sources are read live at query time——即 Linear 数据不再走批量 ETL 落库而是查询时实时读取这也是/sources同步端点返回linear_sources_queued: 0、linear_sync_removed的原因。五、Inbound HTTP 路由/integrations 与 /sources两个 FastAPI 路由文件分别挂载/integrations与/sources前缀由主应用挂载依赖app.core.database.get_db、app.modules.auth.auth_service.AuthService、app.modules.auth.api_key_deps.get_api_key_user。5.1 /integrationsOAuth 全生命周期integrations_router.py 覆盖 initiate → callback → status → revoke → save 的完整闭环。OAuth state 签名防篡改_sign_oauth_state()与_verify_oauth_state()实现了基于 HMAC-SHA256 的有状态签名def _sign_oauth_state(raw_state: str | None, expires: int 600) - str | None: # 形式base64(payload).hex(hmac) # payload 为 JSON: {u: raw_state, e: expiry_ts} ... sig hmac.new(secret.encode(utf-8), payload_b64.encode(utf-8), hashlib.sha256).hexdigest() return f{payload_b64}.{sig}验证时用hmac.compare_digest做常数时间比较并检查过期时间若未配置OAUTH_STATE_SECRET则退化为不签名开发环境兜底。Linear 的 initiate 端点还会把已认证用户的user_id签入 state身份来自AuthService.check_auth而非请求体从而在回调阶段免登录地识别用户。关键端点速览方法路径说明POST/integrations/sentry/initiate返回 Sentry 授权 URLstate 签名GET/integrations/sentry/callback校验 state 后由客户端处理回调GET/integrations/sentry/status/{user_id}查询连接状态校验登录用户 user_idDELETE/integrations/sentry/revoke/{user_id}撤销访问POST/integrations/linear/initiate服务端发起 Linear OAuth返回authorization_urlscope 默认readGET/integrations/linear/redirect直接跳转授权明确拒绝携带 code 的伪回调GET/integrations/linear/callback交换 code → 保存集成 → 302 跳转前端POST/integrations/linear/save前端回传 code 的保存入口POST/GET/integrations/jira/initiate|callbackJira OAuthcallback 中按JIRA_REDIRECT_URI或请求 scheme/host 拼回调地址GET/integrations/jira/{id}/resources|projects拉取可访问资源与项目校验集成归属GET/integrations/jira/{id}/projects/{key}项目详情linear/callback的跳转逻辑体现了完整的前后端衔接成功后跳{FRONTEND_URL}/integrations/linear/redirect?successtrueintegration_id...user_name...捕获到LinearOrganizationAlreadyIntegratedError时跳?successtruealready_existstrueintegration_id...其余异常 URL 编码错误消息后跳?error...。FRONTEND_URL缺省为http://localhost:3000。5.2 /sourcesProvider 目录与项目源 APIsources_router.py 是统一 Sources API端点如下方法路径说明GET/sources/providers调用load_providers()后返回 Provider 目录id、display_name、capabilities、source_kinds、port_kind、oss_availableGET/sources/connections汇总当前用户的连接GitHub来自UserAuthProvider的firebase_github行与 active 的 Linear 集成GET/sources/linear/teams按integration_id解密 token 实时查询 Linear 团队列表GET/sources/projects/{project_id}/sources列出项目的全部源POST/sources/projects/{project_id}/sources/linear挂载 Linear 团队body 含integration_id、team_id、可选team_nameValueError映射为 404DELETE/sources/projects/{project_id}/sources/{source_id}解绑项目源POST/sources/projects/{project_id}/sources/sync触发整项目同步存在启用的 GitHub 源时调用submit_agent_reconciliation(db, project_id, triggersources_sync)Linear 计为 0POST/sources/projects/{project_id}/sources/{source_id}/sync单源同步Linear 返回skipped/linear_sync_removedGitHub 入队 reconciliationPOST/sources/webhooks/linearLinear 事件 webhook校验Linear-Signature后解析teamId并确认接收不入队其中 webhook 端点实现了HMAC 签名校验配置了LINEAR_WEBHOOK_SECRET时缺失Linear-Signature头返回 401签名不匹配返回 401随后解析 JSON 提取action与team_id兼容 payload 中teamId与嵌套team.id两种位置最终按Linear 实时读取策略确认接收而不入队。六、安全与可观测性实践从路由与服务层可以提炼出三条贯穿始终的安全实践日志脱敏hash_user_id()见 integrations/init.py对 user_id 取 SHA256 前 8 位后记录sanitize_headers()将 authorization、cookie、token 等敏感头替换为[REDACTED]truncate_content()限制日志中正文长度。OAuth token 交换与刷新均遵循错误级别只记状态码与截断错误、debug 级别才记完整响应的分级策略。越权防护status/revoke端点统一校验user[user_id] user_id否则 403/sources的挂载、解绑、同步均以Project.user_id uid校验项目归属。凭证加密所有 token 落库前加密出库时解密且授权码交换后立即置空。七、测试与质量保障模块测试位于 potpie/integrations/testspyproject.toml 中配置了 pytest 参数[tool.pytest.ini_options] testpaths [tests] python_files [test_*.py] addopts -v --tbshort asyncio_mode auto markers [integration: HTTP/router integration tests (legacy app host)]asyncio_mode auto表明测试覆盖异步路由与 service 方法integration/test_linear_oauth_initiate.py 覆盖 Linear OAuth 发起流程HTTP/router 集成测试marker 注释注明面向 legacy app hosttest_logging.py 验证日志模块行为tests/conftest.py提供共享夹具配合reset_provider_registry_for_tests()、reset_load_providers_for_tests()实现 Provider 注册表的测试隔离。八、环境变量速查综合路由与服务层代码该模块运行时依赖以下配置项均通过Config()读取部分带默认值变量用途默认值SENTRY_CLIENT_ID/SENTRY_CLIENT_SECRET/SENTRY_REDIRECT_URISentry OAuth 应用凭证与回调地址空未配置时报错JIRA_REDIRECT_URIJira 回调地址缺省按请求 scheme/host 拼接/api/v1/integrations/jira/callback空OAUTH_STATE_SECRETOAuth state 的 HMAC 签名密钥未配置时不签名开发兜底空LINEAR_WEBHOOK_SECRET校验Linear-Signature未配置时跳过校验空FRONTEND_URLOAuth 回调后前端跳转地址http://localhost:3000九、扩展方式与演进方向基于源码结构推断新增 Provider在adapters/outbound/providers/新增register_xxx_provider(registry)并在bootstrap.load_providers()中调用即可扩展目录商业插件则通过独立包potpie_integrations_commercial.register_providers动态注入无需改动 OSS 代码——这是_try_register_commercial留出的明确扩展点。集成类型扩展IntegrationType枚举已预留slack类型save_integration通用模型可支撑手动创建但对应的 OAuth 客户端与 webhook 处理仍需在 service/router 层补充。数据同步策略从/sources路由的注释可推断Linear 已从批量 ETL 迁移为查询时实时读取而 GitHub 源仍通过submit_agent_reconciliation入队 Agent 调和任务两种数据源采用不同的同步哲学。从整体看potpie-integrations通过镜像 context-engine 的六边形布局 独立顶层包名 可插拔 Provider 注册表 统一的 Schema 契约为 Potpie 的 AI Native SDLC 场景提供了稳定、可审计、易扩展的外部服务接入层。开发者若要为 Potpie 增加新的第三方集成完全可以参照本文的目录结构与服务流程在模块内完成接入。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考