From 82c27dab5e0b0235acb3e59861aeb31fde704154 Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Sat, 21 Mar 2026 17:05:21 +0800 Subject: [PATCH] chore: align repository docs and ci --- .github/ISSUE_TEMPLATE/bug_report.yml | 184 +++-------- .github/ISSUE_TEMPLATE/config.yml | 21 +- .github/ISSUE_TEMPLATE/documentation.yml | 172 ---------- .github/ISSUE_TEMPLATE/feature_request.yml | 165 ++-------- .github/ISSUE_TEMPLATE/performance_issue.yml | 236 -------------- .github/ISSUE_TEMPLATE/platform_request.yml | 233 -------------- .github/pull_request_template.md | 113 +------ CODE_OF_CONDUCT.md | 114 +++---- CONTRIBUTING.md | 299 ++++++------------ GOVERNANCE.md | 70 ++++ README.md | 6 + README.zh-Hans.md | 6 + README.zh-Hant.md | 6 + SECURITY.md | 172 +++------- adapters/functions/api/index.js | 2 +- adapters/functions/deno.js | 2 +- .../netlify/edge-functions/edge-handler.js | 3 +- adapters/pages/functions/[[path]].js | 2 +- skills/xget/scripts/xget.mjs | 2 - src/app/handle-request.js | 8 +- src/config/index.js | 2 +- src/config/platform-catalog.js | 2 +- src/index.js | 2 +- src/protocols/ai.js | 2 +- src/protocols/docker.js | 2 +- src/protocols/git.js | 2 +- src/protocols/huggingface.js | 2 +- src/utils/performance.js | 2 +- src/utils/security.js | 2 +- src/utils/validation.js | 2 +- 30 files changed, 392 insertions(+), 1444 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/documentation.yml delete mode 100644 .github/ISSUE_TEMPLATE/performance_issue.yml delete mode 100644 .github/ISSUE_TEMPLATE/platform_request.yml create mode 100644 GOVERNANCE.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 966cfe7..d1c1dfe 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,167 +1,67 @@ -name: 🐛 bug 报告 -description: 报告一个问题或错误 +name: Bug report +description: Report a reproducible problem in Xget title: "[Bug]: " -labels: ["bug", "需要分类"] -assignees: [] - +labels: + - bug body: - type: markdown attributes: value: | - 感谢你花时间填写这个 bug 报告！请尽可能详细地描述问题，这将帮助我们更快地定位和修复问题。 - - - type: checkboxes - id: prerequisites - attributes: - label: 前置检查 - description: 在提交 Issue 之前，请确认以下事项 - options: - - label: 我已经搜索过现有的 Issues，确认这不是重复问题 - required: true - - label: 我已经查看过文档和 README - required: true - - label: 我已经确认当前部署配置与文档一致 - required: false + Thanks for taking the time to report a bug. + Please search existing issues before filing a new one. If this is a security + vulnerability, do not continue here. Follow the private reporting instructions + in [SECURITY.md](https://github.com/xixu-me/Xget/blob/main/SECURITY.md). - type: textarea - id: description + id: summary attributes: - label: 问题描述 - description: 清晰简洁地描述遇到的问题 - placeholder: 描述你遇到了什么问题... + label: What happened? + description: Describe the problem and the actual behavior you observed. + placeholder: A request to /npm/... returns the wrong upstream path when... validations: required: true - - - type: textarea - id: reproduction - attributes: - label: 重现步骤 - description: 提供重现问题的详细步骤 - placeholder: | - 1. 访问 '...' - 2. 执行命令 '...' - 3. 观察到错误 '...' - value: | - 1. - 2. - 3. - validations: - required: true - - type: textarea id: expected attributes: - label: 期望行为 - description: 描述你期望发生什么 - placeholder: 应该... + label: What did you expect to happen? + placeholder: The request should be rewritten to... + validations: + required: true + - type: dropdown + id: area + attributes: + label: Which area is affected? + options: + - Routing or path transformation + - Git protocol + - Docker or OCI registry support + - AI inference proxying + - Cache behavior + - Security headers or validation + - Deployment or adapter behavior + - Documentation + - Something else validations: required: true - - type: textarea - id: actual + id: reproduction attributes: - label: 实际行为 - description: 描述实际发生了什么 - placeholder: 但实际上... + label: Steps to reproduce + description: Share a minimal reproduction with secrets removed. + placeholder: | + 1. Send request to... + 2. Use headers... + 3. Observe... validations: required: true - - - type: dropdown - id: platform - attributes: - label: 受影响的平台 - description: 选择问题相关的平台（可多选） - multiple: true - options: - - GitHub - - GitLab - - npm - - PyPI - - Docker Hub - - crates.io - - Maven Central - - Homebrew - - Jenkins - - OpenAI API - - Anthropic API - - 其他 AI 推理 API - - 不确定/不适用 - validations: - required: true - - - type: dropdown - id: request_type - attributes: - label: 请求类型 - description: 选择问题相关的请求类型 - options: - - Git 克隆/拉取 - - Git LFS - - Docker 镜像拉取 - - 包下载 (npm/PyPI/Maven 等) - - AI API 推理请求 - - 其他 - validations: - required: true - - type: textarea id: environment attributes: - label: 环境信息 - description: 提供你的环境详细信息 - value: | - - 操作系统: [例如 Ubuntu 22.04, macOS 14, Windows 11] - - 客户端工具: [例如 git 2.40, docker 24.0, npm 10.2] - - 浏览器 (如适用): [例如 Chrome 120, Firefox 121] - - Xget 部署方式: [Cloudflare Workers / 自托管 / 其他] - validations: - required: true - - - type: textarea - id: logs - attributes: - label: 错误日志 - description: | - 提供相关的错误日志、堆栈跟踪或控制台输出 - 提示: 你可以在代码块中粘贴日志以保持格式 - render: shell - placeholder: | - 粘贴错误日志... - - - type: textarea - id: curl - attributes: - label: cURL 命令或请求示例 - description: 如果可能，提供能重现问题的 cURL 命令或请求示例（请移除敏感信息） - render: shell - placeholder: | - curl -X GET "https://your-xget-instance/gh/microsoft/vscode" -H "User-Agent: git/2.40" - + label: Environment + description: Include runtime, deployment target, client, and version details when relevant. + placeholder: Cloudflare Workers, local wrangler dev, curl 8.8.0, Node.js 24... - type: textarea id: additional attributes: - label: 附加信息 - description: | - 提供任何其他有助于理解问题的上下文、截图或信息 - 提示: 你可以拖拽图片到这里上传 - - - type: dropdown - id: severity - attributes: - label: 严重程度 - description: 这个问题对你的影响有多大？ - options: - - 严重 - 核心功能完全无法使用 - - 高 - 重要功能受阻 - - 中 - 功能可用但有明显问题 - - 低 - 轻微问题或不便 - validations: - required: true - - - type: checkboxes - id: contribution - attributes: - label: 贡献意愿 - description: 你是否愿意提交 PR 来修复这个问题？ - options: - - label: 我愿意提交 PR 来修复这个问题 + label: Additional context + description: Logs, headers, screenshots, or links that help explain the issue. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 8c348fc..6095d5e 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,11 +1,14 @@ blank_issues_enabled: false contact_links: - - name: 📚 文档 - url: https://github.com/xixu-me/Xget/blob/main/README.zh-Hans.md - about: 查看存储库的 README 文档 - - name: 🔁 URL 转换器 - url: https://xuc.xi-xu.me - about: 访问配套 web 应用程序 - - name: 🔐 安全漏洞报告 - url: https://github.com/xixu-me/xget/security/policy#-%E6%8A%A5%E5%91%8A%E5%AE%89%E5%85%A8%E6%BC%8F%E6%B4%9E - about: 报告安全漏洞 + - name: Read the README + url: https://github.com/xixu-me/Xget/blob/main/README.md + about: Check supported platforms, usage examples, and deployment options first. + - name: Contributing Guide + url: https://github.com/xixu-me/Xget/blob/main/CONTRIBUTING.md + about: Learn how to prepare a bug report or pull request. + - name: Security Policy + url: https://github.com/xixu-me/Xget/blob/main/SECURITY.md + about: Use this for private vulnerability reporting instructions. + - name: Maintainer contact page + url: https://xi-xu.me/#contact + about: Use a private contact path for sensitive or non-public matters. diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml deleted file mode 100644 index 6cac3e8..0000000 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ /dev/null @@ -1,172 +0,0 @@ -name: 📝 文档改进 -description: 报告文档问题或建议文档改进 -title: "[Docs]: " -labels: ["documentation", "需要分类"] -assignees: [] - -body: - - type: markdown - attributes: - value: | - 感谢你帮助改进文档！清晰准确的文档对存储库至关重要。 - - - type: dropdown - id: doc_type - attributes: - label: 文档类型 - description: 这涉及哪种类型的文档？ - options: - - README - - CLAUDE.md - - API 文档 - - 部署指南 - - 配置说明 - - 使用教程 - - 开发文档 - - 代码注释 - - 其他 - validations: - required: true - - - type: dropdown - id: issue_category - attributes: - label: 问题类别 - description: 选择文档问题的类别 - options: - - 内容缺失 - - 内容过时 - - 内容错误 - - 不够清晰 - - 示例缺失 - - 示例错误 - - 格式问题 - - 翻译问题 - - 组织结构问题 - - 新内容建议 - validations: - required: true - - - type: textarea - id: location - attributes: - label: 文档位置 - description: 指出具体的文档位置 - placeholder: | - - 文件: README.md - - 章节: "部署到 Cloudflare Workers" - - 行号: 约 L123-L145 - - URL: https://github.com/.../blob/main/... - validations: - required: true - - - type: textarea - id: current_content - attributes: - label: 当前内容 - description: 引用当前的文档内容（如果适用） - placeholder: | - 当前文档中写的是: - > "..." - render: markdown - - - type: textarea - id: issue_description - attributes: - label: 问题描述 - description: 详细描述文档存在的问题 - placeholder: | - 这个文档有以下问题: - 1. - 2. - validations: - required: true - - - type: textarea - id: suggested_content - attributes: - label: 建议的改进 - description: 提供具体的改进建议或修正后的内容 - placeholder: | - 建议改为: - "..." - - 或者添加以下内容: - "..." - render: markdown - validations: - required: true - - - type: textarea - id: why_important - attributes: - label: 重要性说明 - description: 解释为什么这个改进很重要 - placeholder: | - 这个改进很重要因为: - - 现在的文档导致用户... - - 这是新用户常见的困惑点... - - 可以帮助用户更快地... - - - type: textarea - id: user_perspective - attributes: - label: 用户视角 - description: 从哪种用户的角度看这个文档问题？ - placeholder: | - - 新用户首次部署 - - 开发者集成 Xget - - 贡献者了解代码结构 - - 运维人员配置环境 - - - type: textarea - id: examples - attributes: - label: 示例需求 - description: 如果需要添加示例，请描述所需的示例类型 - placeholder: | - 希望添加以下示例: - - Git 克隆的完整命令示例 - - Docker 拉取镜像的配置示例 - - 环境变量配置的实际案例 - - - type: checkboxes - id: language - attributes: - label: 语言版本 - description: 这个问题涉及哪些语言版本？（可多选） - options: - - label: 中文文档 - - label: 英文文档 - - label: 其他语言 - - - type: checkboxes - id: related_areas - attributes: - label: 相关领域 - description: 这个文档改进可能涉及哪些领域？（可多选） - options: - - label: 快速开始指南 - - label: 安装部署 - - label: 配置说明 - - label: 平台使用 - - label: API 参考 - - label: 故障排查 - - label: 性能优化 - - label: 安全配置 - - label: 开发贡献 - - label: 架构设计 - - - type: checkboxes - id: contribution - attributes: - label: 贡献意愿 - options: - - label: 我愿意提交 PR 来改进这个文档 - - label: 我可以帮助审阅文档改进 - - - type: textarea - id: additional - attributes: - label: 附加信息 - description: 提供任何其他有助于改进文档的信息或建议 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 1edeaff..663dd35 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,167 +1,46 @@ -name: ✨ 功能请求 -description: 建议一个新功能或改进 +name: Feature request +description: Propose an improvement or new capability for Xget title: "[Feature]: " -labels: ["enhancement", "需要分类"] -assignees: [] - +labels: + - enhancement body: - type: markdown attributes: value: | - 感谢你提出新功能建议！请详细描述你的想法，这将帮助我们更好地评估和实现。 - - - type: checkboxes - id: prerequisites - attributes: - label: 前置检查 - description: 在提交功能请求之前，请确认以下事项 - options: - - label: 我已经搜索过现有的 Issues 和 PR，确认这不是重复请求 - required: true - - label: 我已经查看过存储库文档 - required: true - - - type: dropdown - id: feature_type - attributes: - label: 功能类型 - description: 这个请求属于什么类型？ - options: - - 新协议支持 - - 性能优化 - - 缓存改进 - - 安全增强 - - 监控/日志功能 - - 配置选项 - - API 改进 - - 文档改进 - - 开发体验改进 - - 其他 - validations: - required: true + Thanks for sharing an idea. + Please keep requests focused and explain the user or maintainer value clearly. + For large changes, starting with an issue before implementation is strongly preferred. - type: textarea id: problem attributes: - label: 问题背景 - description: 描述你想解决的问题或痛点 - placeholder: | - 我在使用 Xget 时遇到了... - 当前的方式是...，但是... + label: What problem are you trying to solve? + description: Describe the user need, operational pain point, or workflow gap. + placeholder: Users of platform X cannot... validations: required: true - - type: textarea - id: solution + id: proposal attributes: - label: 建议的解决方案 - description: 清晰地描述你希望实现的功能 - placeholder: 我希望 Xget 能够... + label: What change would you like to see? + description: Describe the proposed behavior or feature. + placeholder: Add support for... validations: required: true - - type: textarea id: alternatives attributes: - label: 备选方案 - description: 描述你考虑过的其他替代解决方案 - placeholder: | - 我也考虑过... - 但这个方案的问题是... - + label: Alternatives considered + description: Describe any workarounds or alternative approaches you evaluated. - type: textarea - id: use_case - attributes: - label: 使用场景 - description: 描述具体的使用场景和预期效果 - placeholder: | - 场景 1: 当用户...时，这个功能可以... - 场景 2: 在...情况下，能够... - validations: - required: true - - - type: dropdown - id: priority - attributes: - label: 优先级 - description: 这个功能对你有多重要？ - options: - - 高 - 对我的工作流程至关重要 - - 中 - 会显著改善使用体验 - - 低 - 有更好，但不是必需的 - validations: - required: true - - - type: textarea - id: platform_specific - attributes: - label: 特定平台需求 - description: 如果这是平台相关的功能请求，请提供详细信息 - placeholder: | - - 平台名称: - - 平台 URL: - - API 文档: - - 认证方式: - - 特殊要求: - - - type: textarea - id: technical_details - attributes: - label: 技术细节 - description: 如果你有技术实现建议，请在此描述 - placeholder: | - 实现方式可能包括: - 1. 在 platforms.js 中添加... - 2. 需要处理...协议 - 3. 可能的挑战是... - - - type: textarea - id: examples - attributes: - label: 示例和参考 - description: 提供相关的示例、链接或参考实现 - placeholder: | - - 类似实现: - - 官方文档: - - 示例请求: - - - type: checkboxes id: impact attributes: - label: 影响范围 - description: 这个功能可能影响哪些方面？（可多选） - options: - - label: 核心请求处理逻辑 - - label: 平台配置 - - label: 协议处理 - - label: 缓存策略 - - label: 安全性 - - label: 性能 - - label: 配置选项 - - label: 文档 - - label: 部署流程 - - - type: checkboxes - id: breaking - attributes: - label: 破坏性变更 - description: 这个功能是否可能引入破坏性变更？ - options: - - label: 可能需要破坏性变更 - - label: 向后兼容 - - - type: checkboxes - id: contribution - attributes: - label: 贡献意愿 - description: 你是否愿意参与实现这个功能？ - options: - - label: 我愿意提交 PR 来实现这个功能 - - label: 我可以提供测试和反馈 - - label: 我可以帮助编写文档 - + label: Why is this valuable? + description: Explain who benefits and why the change fits Xget's goals. + validations: + required: true - type: textarea id: additional attributes: - label: 附加信息 - description: 提供任何其他有助于理解这个功能请求的信息 + label: Additional context + description: Add links, examples, or prior art if helpful. diff --git a/.github/ISSUE_TEMPLATE/performance_issue.yml b/.github/ISSUE_TEMPLATE/performance_issue.yml deleted file mode 100644 index 919db6c..0000000 --- a/.github/ISSUE_TEMPLATE/performance_issue.yml +++ /dev/null @@ -1,236 +0,0 @@ -name: ⚡ 性能问题 -description: 报告性能相关的问题或建议性能优化 -title: "[Performance]: " -labels: ["performance", "需要分类"] -assignees: [] - -body: - - type: markdown - attributes: - value: | - 感谢你报告性能问题！请提供详细的性能指标和场景，这将帮助我们诊断和优化。 - - - type: checkboxes - id: prerequisites - attributes: - label: 前置检查 - options: - - label: 我已经搜索过现有的性能相关 Issues - required: true - - label: 我已经确认这不是上游平台本身的性能问题 - required: true - - - type: dropdown - id: issue_type - attributes: - label: 问题类型 - description: 选择性能问题的类型 - options: - - 响应时间过长 - - 超时错误 - - 高延迟 - - 带宽限制 - - 缓存未命中 - - 内存使用过高 - - 并发性能问题 - - 其他 - validations: - required: true - - - type: dropdown - id: affected_platform - attributes: - label: 受影响的平台 - description: 哪个平台的性能出现问题？ - options: - - GitHub - - GitLab - - npm - - PyPI - - Docker Hub - - crates.io - - Maven Central - - Homebrew - - Jenkins - - OpenAI API - - Anthropic API - - 多个平台 - - 所有平台 - validations: - required: true - - - type: dropdown - id: operation_type - attributes: - label: 操作类型 - description: 什么类型的操作性能有问题？ - options: - - Git 克隆 - - Git 拉取 - - Git LFS 下载 - - Docker 镜像拉取 - - 包下载 - - AI API 请求 - - 元数据获取 - - 其他 - validations: - required: true - - - type: textarea - id: description - attributes: - label: 问题描述 - description: 详细描述性能问题 - placeholder: | - 在执行...操作时，性能明显低于预期... - 相比直接访问上游，速度慢了... - validations: - required: true - - - type: textarea - id: metrics - attributes: - label: 性能指标 - description: 提供具体的性能数据 - placeholder: | - - 响应时间: XX ms (预期 < YY ms) - - 下载速度: XX KB/s (上游直连: YY KB/s) - - 首字节时间 (TTFB): XX ms - - 总耗时: XX 秒 - - X-Performance-Metrics 头信息: {...} - render: markdown - validations: - required: true - - - type: textarea - id: reproduction - attributes: - label: 重现步骤 - description: 提供详细的重现步骤和测试命令 - render: shell - placeholder: | - # 测试命令 - time git clone https://your-xget-instance/gh/user/repo - - # 或使用 curl 测试 - curl -w "@curl-format.txt" -o /dev/null https://your-xget-instance/... - validations: - required: true - - - type: textarea - id: environment - attributes: - label: 环境信息 - description: 提供详细的环境信息 - value: | - - Xget 部署方式: [Cloudflare Workers / 自托管 / ...] - - Xget 区域: [US/EU/ASIA/...] - - 客户端位置: [国家/地区] - - 网络环境: [家庭宽带 / 公司网络 / VPS / ...] - - ISP: - - 客户端工具版本: - - 操作系统: - validations: - required: true - - - type: textarea - id: resource_size - attributes: - label: 资源规模 - description: 描述涉及的资源大小 - placeholder: | - - 存储库大小: XX MB - - 文件数量: XX 个 - - 单个文件大小: XX MB - - Docker 镜像大小: XX GB - - 镜像层数: XX 层 - - - type: textarea - id: comparison - attributes: - label: 性能对比 - description: 对比 Xget 与直接访问上游的性能差异 - placeholder: | - | 操作 | 通过 Xget | 直接访问上游 | 差异 | - |------|-----------|--------------|------| - | 克隆 | 30s | 10s | +200% | - | 拉取 | 5s | 2s | +150% | - render: markdown - - - type: textarea - id: cache_info - attributes: - label: 缓存信息 - description: 检查响应的缓存相关 Header - placeholder: | - - CF-Cache-Status: - - X-Cache-Status: - - Age: - - Cache-Control: - render: markdown - - - type: textarea - id: network_trace - attributes: - label: 网络追踪 - description: 如果可能，提供网络追踪信息（如 curl -v 输出的关键部分） - render: shell - placeholder: | - * Connected to your-xget-instance (...) - * TLS handshake... - < HTTP/2 200 - < x-performance-metrics: {...} - - - type: dropdown - id: frequency - attributes: - label: 问题频率 - description: 这个性能问题多久发生一次？ - options: - - 每次都发生 - - 经常发生 (>50%) - - 偶尔发生 (10-50%) - - 很少发生 (<10%) - validations: - required: true - - - type: dropdown - id: impact - attributes: - label: 影响程度 - description: 这个性能问题的影响有多大？ - options: - - 严重 - 完全无法使用 - - 高 - 严重影响工作效率 - - 中 - 造成明显不便 - - 低 - 轻微影响 - validations: - required: true - - - type: textarea - id: expected_performance - attributes: - label: 期望的性能 - description: 描述你期望的性能指标 - placeholder: | - - 理想响应时间: < 100ms - - 可接受的下载速度: > 1MB/s - - 目标改进: 减少 50% 的延迟 - - - type: textarea - id: suggestions - attributes: - label: 优化建议 - description: 如果你有优化建议，请在此描述 - placeholder: | - 可能的优化方向: - - 增加缓存时长 - - 使用流式传输 - - 优化重试策略 - - ... - - - type: textarea - id: additional - attributes: - label: 附加信息 - description: 提供任何其他有助于诊断性能问题的信息 diff --git a/.github/ISSUE_TEMPLATE/platform_request.yml b/.github/ISSUE_TEMPLATE/platform_request.yml deleted file mode 100644 index 6b93746..0000000 --- a/.github/ISSUE_TEMPLATE/platform_request.yml +++ /dev/null @@ -1,233 +0,0 @@ -name: 🌐 新平台支持请求 -description: 请求添加对新平台的支持 -title: "[Platform]: " -labels: ["platform", "enhancement", "需要分类"] -assignees: [] - -body: - - type: markdown - attributes: - value: | - 感谢你提出新平台支持请求！请提供尽可能详细的平台信息，以便我们评估和实现。 - - - type: checkboxes - id: prerequisites - attributes: - label: 前置检查 - options: - - label: 我已经搜索过现有的 Issues，确认这个平台还未被请求或支持 - required: true - - label: 这个平台是公开可访问的服务 - required: true - - - type: input - id: platform_name - attributes: - label: 平台名称 - description: 请提供平台的官方名称 - placeholder: "例如: GitLab, Bitbucket, Quay.io" - validations: - required: true - - - type: input - id: platform_url - attributes: - label: 平台 URL - description: 平台的主要域名或网址 - placeholder: "例如: https://registry.example.com" - validations: - required: true - - - type: dropdown - id: platform_category - attributes: - label: 平台类别 - description: 这个平台属于什么类别？ - options: - - 代码存储库 (Git) - - 容器注册表 (Docker/OCI) - - 软件包注册表 (npm/PyPI/Maven 等) - - AI 推理提供商 - - CDN/文件存储 - - 其他 - validations: - required: true - - - type: textarea - id: platform_description - attributes: - label: 平台描述 - description: 简要描述这个平台的用途和特点 - placeholder: 这个平台是一个...，主要用于... - validations: - required: true - - - type: textarea - id: use_case - attributes: - label: 使用场景 - description: 为什么需要加速这个平台？具体的使用场景是什么？ - placeholder: | - 在中国大陆访问该平台时... - 我的团队经常需要从该平台下载... - 加速该平台可以帮助... - validations: - required: true - - - type: textarea - id: api_documentation - attributes: - label: API 文档 - description: 提供平台的 API 文档链接（如果有） - placeholder: | - - 官方 API 文档: - - 认证文档: - - 其他相关文档: - - - type: dropdown - id: authentication - attributes: - label: 认证方式 - description: 该平台使用什么认证方式？ - options: - - 无需认证（公开访问） - - API Token - - OAuth 2.0 - - Basic Auth - - Bearer Token - - 自定义认证 - - 不确定 - validations: - required: true - - - type: textarea - id: auth_details - attributes: - label: 认证详情 - description: 如果需要认证，请提供详细的认证流程说明 - placeholder: | - 该平台的认证流程: - 1. - 2. - 3. - - - type: dropdown - id: protocol - attributes: - label: 主要协议 - description: 访问该平台主要使用什么协议？ - options: - - HTTP/HTTPS (RESTful API) - - Git Protocol - - Docker Registry V2 - - OCI Distribution Spec - - 其他/混合 - validations: - required: true - - - type: textarea - id: url_structure - attributes: - label: URL 结构示例 - description: 提供该平台的典型 URL 结构和示例 - placeholder: | - 示例 URL: - - 下载包: https://example.com/packages/{name}/{version} - - 存储库克隆: https://example.com/repos/{owner}/{repo}.git - - API 端点: https://api.example.com/v1/... - render: markdown - validations: - required: true - - - type: textarea - id: special_requirements - attributes: - label: 特殊要求 - description: 该平台是否有特殊的 Header、参数或处理要求？ - placeholder: | - - 必需的 Headers: - - 特殊的查询参数: - - 响应格式: - - URL 重写需求: - - 其他特殊处理: - - - type: textarea - id: request_examples - attributes: - label: 请求示例 - description: 提供一些典型的请求示例（请移除敏感信息） - render: shell - placeholder: | - # 示例 1: 获取包信息 - curl -X GET "https://example.com/api/packages/foo" - - # 示例 2: 下载文件 - curl -X GET "https://example.com/files/bar.tar.gz" - - - type: textarea - id: response_examples - attributes: - label: 响应示例 - description: 提供典型响应的示例（可以是简化版本） - render: json - placeholder: | - { - "name": "example-package", - "version": "1.0.0", - "download_url": "https://example.com/files/..." - } - - - type: textarea - id: challenges - attributes: - label: 潜在挑战 - description: 你认为支持这个平台可能遇到哪些挑战？ - placeholder: | - - 该平台使用自定义的认证方式... - - URL 结构比较复杂... - - 需要处理特殊的重定向... - - - type: textarea - id: similar_platforms - attributes: - label: 类似平台 - description: 列出 Xget 已支持的类似平台（如果有） - placeholder: | - 这个平台类似于已支持的: - - npm (软件包注册表) - - Docker Hub (容器注册表) - - - type: input - id: estimated_users - attributes: - label: 用户基数 - description: 该平台的大致用户规模或你所在团队/社区的使用情况 - placeholder: "例如: 国内有约 XX 万开发者使用，我的团队有 20 人使用" - - - type: dropdown - id: priority - attributes: - label: 优先级 - description: 这个平台支持对你有多重要？ - options: - - 高 - 我们团队急需 - - 中 - 会显著改善工作流程 - - 低 - 有更好，但不紧急 - validations: - required: true - - - type: checkboxes - id: contribution - attributes: - label: 贡献意愿 - options: - - label: 我愿意提供该平台的测试账号（如果需要） - - label: 我愿意协助测试平台支持 - - label: 我愿意提交 PR 来实现平台支持 - - label: 我可以提供更多技术文档和细节 - - - type: textarea - id: additional - attributes: - label: 附加信息 - description: 提供任何其他有助于实现这个平台支持的信息 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8d0a242..42bbc54 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,106 +1,23 @@ -## 概述 +## Summary - +- What does this change do? +- Why is it needed? -## 改动类型 +## Testing - - -- [ ] 🐛 bug 修复 -- [ ] ✨ 新功能 -- [ ] 📝 文档更新 -- [ ] 🎨 代码风格/格式调整 -- [ ] ♻️ 代码重构 -- [ ] ⚡️ 性能优化 -- [ ] ✅ 测试相关 -- [ ] 🔧 配置文件修改 -- [ ] 🌐 新增平台支持 -- [ ] 🔒 安全相关 - -## 相关 Issue - - - -Closes # -Related to # - -## 改动说明 - - - -### 主要改动 - -- - -### 技术细节 - -- - -## 测试 - - - -- [ ] 已通过所有现有测试 (`npm run test:run`) -- [ ] 已添加新的测试用例 -- [ ] 已在本地开发环境测试 (`npm run dev`) -- [ ] 已验证代码格式 (`npm run format:check`) -- [ ] 已通过类型检查 (`npm run type-check`) -- [ ] 已通过 lint 检查 (`npm run lint`) - -### 测试环境 - - - -- - -## 影响范围 - - - -- [ ] 核心请求处理逻辑 -- [ ] 平台配置 -- [ ] 协议处理 (Git/Docker/AI) -- [ ] 缓存策略 -- [ ] 安全功能 -- [ ] 性能监控 -- [ ] 文档 -- [ ] CI/CD 流程 - -## 破坏性变更 - - - -- [ ] 是 -- [ ] 否 - -
-破坏性变更详情 - - - -
- -## 部署说明 - - - -- - -## 截图/演示 - - +- [ ] `npm run lint` +- [ ] `npm run format:check` +- [ ] `npm run test:run` +- [ ] `npm run type-check` ## Checklist -- [ ] 代码遵循存储库的编码规范 -- [ ] 已进行自我代码审查 -- [ ] 代码注释清晰，特别是复杂逻辑部分 -- [ ] 已更新相关文档 -- [ ] 改动不会产生新的警告 -- [ ] 已添加必要的测试，且测试通过 -- [ ] 新增和现有的单元测试都通过 -- [ ] 依赖的改动已合并并发布 +- [ ] I kept the change focused and avoided unrelated edits +- [ ] I added or updated tests when behavior changed +- [ ] I updated documentation when user-facing behavior changed +- [ ] I removed or redacted secrets, tokens, and private data from examples -## 附加说明 +## Notes for reviewers - +- Related issue: +- Risk or rollout notes: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index bfa6311..23489c1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,80 +1,80 @@ -# 贡献者行为准则 +# Code of Conduct -## 我们的承诺 +## Our commitment -作为成员、贡献者和领导者，我们承诺让每个人都能在我们的社区中获得无骚扰的体验，无论其年龄、体型、明显或不明显的残疾、种族、性别特征、性别认同和表达、经验水平、教育程度、社会经济地位、国籍、外貌、种族、宗教或性取向如何。 +Xget aims to be a welcoming, respectful, and technically constructive open +source project. Contributors, maintainers, and community members are expected to +help create an environment where people can ask questions, share ideas, and +collaborate without harassment or hostility. -我们承诺以有助于建立开放、友好、多元、包容和健康社区的方式行事和互动。 +## Scope -## 我们的标准 +This code of conduct applies to project spaces, including: -有助于为我们社区创造积极环境的行为示例包括： +- GitHub issues, pull requests, reviews, and discussions +- Documentation, examples, and other repository content +- Community spaces or events that are explicitly presented as part of Xget -* 对他人表现出同理心和善意 -* 尊重不同的观点、看法和经历 -* 给予并优雅地接受建设性反馈 -* 承担责任并向受我们错误影响的人道歉，并从经验中学习 -* 专注于不仅对我们个人最好，而且对整个社区最好的事情 +## Expected behavior -不可接受的行为示例包括： +- Be respectful and professional, even in disagreement +- Focus feedback on code, design, documentation, and behavior, not on people +- Share context, evidence, and reproduction steps when raising concerns +- Welcome contributors with different backgrounds, skill levels, and use cases +- Accept constructive feedback and course-correction gracefully -* 使用性化的语言或图像，以及任何形式的性关注或性挑逗 -* 恶意评论、侮辱性或贬损性评论，以及个人或政治攻击 -* 公开或私下骚扰 -* 未经明确许可发布他人的私人信息，如物理地址或电子邮件地址 -* 在专业环境中可能被合理认为不当的其他行为 +## Unacceptable behavior -## 执行责任 +- Harassment, intimidation, threats, or personal attacks +- Discriminatory or demeaning language +- Deliberate disruption, trolling, or bad-faith engagement +- Publishing private information without explicit permission +- Sexualized language or imagery in project spaces +- Repeatedly ignoring project rules, review boundaries, or moderator direction -社区领导者有责任澄清和执行我们的可接受行为标准，并将对他们认为不当、威胁、冒犯或有害的任何行为采取适当和公平的纠正措施。 +## Enforcement responsibilities -社区领导者有权利和责任删除、编辑或拒绝与本行为准则不符的评论、提交、代码、wiki 编辑、问题和其他贡献，并在适当时传达审核决定的原因。 +Project maintainers are responsible for clarifying and enforcing these +standards. They may take any action they consider appropriate to protect the +community, including editing or removing content, closing discussions, rejecting +contributions, temporarily restricting participation, or permanently banning a +participant from project spaces. -## 适用范围 +## Reporting concerns -本行为准则适用于所有社区空间，也适用于个人在公共空间正式代表社区的情况。代表我们社区的示例包括使用官方电子邮件地址、通过官方社交媒体账户发布信息，或在线上或线下活动中担任指定代表。 +If you experience or witness behavior that violates this code of conduct, report +it privately to the maintainer using the contact information published on the +maintainer contact page: -## 执行 +- -可以向负责执行的社区领导者报告滥用、骚扰或其他不可接受的行为，联系邮箱：。 -所有投诉都将得到及时和公正的审查和调查。 +Please include: -所有社区领导者都有义务尊重任何事件报告者的隐私和安全。 +- A description of what happened +- Links, screenshots, or other relevant evidence +- When and where the incident occurred +- Any immediate safety or privacy concerns -## 执行指南 +If the report concerns the current primary maintainer, use another private +contact method listed on the same contact page, or GitHub's site-wide reporting +tools when the incident took place on GitHub. -社区领导者将遵循这些社区影响指南来确定他们认为违反本行为准则的任何行为的后果： +## Enforcement process -### 1. 纠正 +- Reports will be reviewed as confidentially as practical +- Maintainers will investigate in good faith and evaluate context carefully +- Outcomes may include a warning, content removal, temporary restriction, or + permanent ban +- Retaliation against someone for making a good-faith report is itself a code of + conduct violation -**社区影响**：使用不当语言或其他被认为在社区中不专业或不受欢迎的行为。 +## Project responsibility -**后果**：社区领导者的私人书面警告，澄清违规的性质并解释为什么该行为不当。可能会要求公开道歉。 +Maintainers are expected to apply this policy fairly and consistently. Not every +disagreement is a code of conduct violation, but behavior that makes the project +unsafe, exclusionary, or hostile will be addressed. -### 2. 警告 +## Attribution -**社区影响**：通过单一事件或一系列行为的违规。 - -**后果**：对持续行为后果的警告。在指定时间内不得与相关人员互动，包括与执行行为准则的人员进行主动互动。这包括避免在社区空间以及社交媒体等外部渠道中的互动。违反这些条款可能导致临时或永久禁令。 - -### 3. 临时禁令 - -**社区影响**：严重违反社区标准，包括持续的不当行为。 - -**后果**：在指定时间内禁止与社区进行任何形式的互动或公开交流。在此期间不允许与相关人员进行公开或私人互动，包括与执行行为准则的人员进行主动互动。违反这些条款可能导致永久禁令。 - -### 4. 永久禁令 - -**社区影响**：表现出违反社区标准的模式，包括持续的不当行为、对个人的骚扰或对某类个人的攻击或贬低。 - -**后果**：永久禁止在社区内进行任何形式的公开互动。 - -## 归属 - -本行为准则改编自[贡献者公约][homepage] 2.0 版，可在 获取。 - -社区影响指南的灵感来自 [Mozilla 的行为准则执行阶梯](https://github.com/mozilla/diversity)。 - -有关本行为准则常见问题的答案，请参阅 的常见问题解答。翻译版本可在 获取。 - -[homepage]: https://www.contributor-covenant.org +This document is informed by the practices recommended by Open Source Guides and +other established open source community standards. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 222da44..7f280ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,245 +1,132 @@ -# 贡献指南 +# Contributing to Xget -感谢您对 Xget 的关注！我们欢迎各种形式的贡献，包括但不限于代码、文档、测试、反馈和建议。 +Thank you for helping improve Xget. Contributions of all sizes are welcome, +including bug reports, documentation improvements, test coverage, performance +investigations, new platform support, and code changes. -## 🤝 贡献方式 +Before you contribute, please read these repository documents: -### 报告问题 +- [README](README.md) for project scope, supported platforms, and deployment + options +- [Code of Conduct](CODE_OF_CONDUCT.md) for community expectations +- [Security Policy](SECURITY.md) for responsible vulnerability reporting +- [Governance](GOVERNANCE.md) for maintainer roles and decision-making -- 使用 - [Issue 模板](https://github.com/xixu-me/Xget/issues/new/choose)报告 bug 或提出功能请求 -- 搜索现有 issues 避免重复报告 -- 提供详细的重现步骤和环境信息 +## Ways to contribute -### 提交代码 +- Report bugs with a minimal reproduction and clear expected behavior +- Propose features that improve correctness, usability, observability, or + maintainability +- Improve documentation, examples, or deployment guidance +- Add or expand automated tests +- Validate behavior against real clients, registries, or upstream platforms -- fork 存储库到您的 GitHub 账户 -- 创建功能分支 (`git checkout -b feature/amazing-feature`) -- 安装依赖以启用本地 Git hooks (`npm install`) -- 使用 Conventional - Commits 提交更改 (`git commit -m 'feat(platforms): add amazing feature'`) -- 推送到分支 (`git push origin feature/amazing-feature`) -- 创建 Pull Request +## Before opening an issue -### 改进文档 +- Search existing issues and pull requests first to avoid duplicates +- Keep one report focused on one problem or one proposal +- Include enough detail for someone else to reproduce the issue +- Do not use public issues for security vulnerabilities; follow + [SECURITY.md](SECURITY.md) instead -- 修正文档中的错误或不准确信息 -- 添加使用示例和最佳实践 -- 翻译文档到其他语言 -- 改进代码注释和 API 文档 +Useful details to include: -## 🛠️ 开发环境设置 +- The request URL or request shape that failed, with secrets removed +- The upstream platform involved, such as GitHub, npm, Docker Hub, or OpenAI +- Expected behavior and actual behavior +- Steps to reproduce the problem +- Logs, screenshots, or response headers when relevant +- Your runtime or deployment environment, if it affects the issue -### 前置要求 +## Development setup -- Node.js 18+ -- npm 或 yarn -- Git -- Cloudflare 账户（用于测试部署） +Xget uses Node.js and Wrangler for local development. -### 本地开发 +1. Install Node.js 24 and npm. +2. Install dependencies with `npm ci`. +3. Start the local worker with `npm run dev`. +4. Run tests and checks before opening a pull request. + +Common commands: ```bash -# 克隆存储库 -git clone https://github.com/xixu-me/Xget.git -cd Xget - -# 安装依赖 -npm install - -# 安装后会自动启用 commit-msg hook - -# 启动开发服务器 npm run dev - -# 单次运行测试 -npm run test:run - -# 代码格式化 -npm run format - -# 代码检查 npm run lint -``` - -## 📝 代码规范 - -### 代码风格 - -- 使用 2 个空格缩进 -- 使用分号结尾 -- 使用单引号字符串 -- 遵循 ESLint 配置规则 - -### 命名约定 - -- 变量和函数使用 camelCase -- 常量使用 UPPER_SNAKE_CASE -- 类名使用 PascalCase -- 文件名使用 kebab-case - -### 注释规范 - -```javascript -/** - * 函数描述 - * @param {string} param1 - 参数1描述 - * @param {Object} param2 - 参数2描述 - * @returns {Promise} 返回值描述 - */ -function exampleFunction(param1, param2) { - // 实现逻辑 -} -``` - -## 🧪 测试 - -### 测试类型 - -- **单元测试**: 测试单个函数和模块 -- **集成测试**: 测试组件间的交互 -- **端到端测试**: 测试完整的用户场景 - -### 运行测试 - -```bash -# 单次运行所有测试 +npm run format:check npm run test:run - -# 运行特定测试文件 -npm run test:run test/platforms/jenkins.test.js - -# 按测试名称筛选 -npm run test:run -- --testNamePattern "platform" - -# 生成测试覆盖率报告 npm run test:coverage +npm run type-check ``` -### 编写测试 +## Repository layout -- 为新功能编写相应的测试 -- 确保测试覆盖率不低于 80% -- 使用描述性的测试名称 -- 测试边界情况和错误处理 +- `src/` contains the Worker entry point, request pipeline, protocol handlers, + routing logic, upstream fetch helpers, and shared utilities +- `test/` contains unit, feature, platform, and integration tests +- `adapters/` contains deployment adapters for non-Workers targets +- `docs/` contains longer-form operational and deployment documentation -## 🚀 提交规范 +## Pull request workflow -### Commit 消息格式 +1. Fork the repository and create a branch from `main`. +2. Keep the change focused. Avoid mixing unrelated fixes. +3. Add or update tests when behavior changes. +4. Update documentation when user-facing behavior, configuration, or supported + platforms change. +5. Run the local checks listed below before requesting review. +6. Open a pull request using the repository template and explain the user impact + clearly. -使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范： - -``` -[optional scope]: - -[optional body] - -[optional footer(s)] -``` - -### 类型说明 - -- `feat`: 新功能 -- `fix`: 修复 bug -- `docs`: 文档更新 -- `style`: 代码格式化（不影响功能） -- `refactor`: 代码重构 -- `perf`: 性能优化 -- `test`: 测试相关 -- `chore`: 构建过程或辅助工具的变动 - -### 示例 +Required local checks: ```bash -feat(platforms): add support for Bitbucket -fix(cache): resolve cache invalidation issue -docs(readme): update installation instructions -perf(proxy): optimize request handling performance +npm run lint +npm run format:check +npm run test:run +npm run type-check ``` -### 自动校验 +If your change affects routing, headers, cache behavior, retries, security +controls, or protocol compatibility, include test coverage for that behavior. -- `npm install` 会自动安装 `commit-msg` hook，在本地阻止不符合规范的提交 -- GitHub Actions 会在 `push` 和 `pull_request` - 中再次校验提交消息，防止绕过本地 hook +## Coding expectations -## 🔍 Pull Request 流程 +- Follow the existing project structure and naming conventions +- Prefer small, reviewable changes over large mixed refactors +- Preserve protocol compatibility for Git, Docker, AI, and package manager + traffic +- Avoid logging secrets, tokens, or private request data +- Document new platform prefixes and examples in [README.md](README.md) when + support is added -### 提交前检查 +## Commit messages -- [ ] 代码通过所有测试 -- [ ] 代码符合存储库规范 -- [ ] 添加了必要的测试 -- [ ] 更新了相关文档 -- [ ] Commit 消息符合规范 +This repository uses +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). +Preferred format: -### PR 描述模板 +```text +type(scope): description +``` -请使用 [PR 模板](.github/pull_request_template.md)填写详细信息。 +Examples: -### 代码审查 +- `feat(docker): normalize blob redirect handling` +- `fix(routing): preserve crates search queries` +- `docs(readme): clarify npm registry setup` -- 所有 PR 需要至少一个维护者的审查 -- 解决审查中提出的问题 -- 保持 PR 的焦点明确，避免混合多个不相关的更改 +## Review and release expectations -## 🌟 贡献认可 +- Maintainers review contributions on a best-effort basis +- Large design changes should start with an issue before implementation +- Merged changes may be edited, squashed, or followed up by maintainers to keep + the project consistent +- Acceptance of a contribution does not create an obligation for long-term + support, backports, or maintenance -### 贡献者列表 +## Community standards -我们会在 README.md 中维护贡献者列表，感谢每一位贡献者的付出。 - -### 贡献统计 - -- 代码贡献会在 GitHub 贡献图中显示 -- 重要贡献会在 Release Notes 中特别提及 -- 长期贡献者可能被邀请成为存储库维护者 - -## 📋 开发任务 - -### 当前优先级 - -1. **性能优化**: 提升缓存效率和响应速度 -2. **平台支持**: 添加新的代码托管和包管理平台 -3. **安全增强**: 加强请求验证和安全防护 -4. **监控改进**: 完善性能监控和错误追踪 - -### 适合新手的任务 - -查找标有 `good first issue` 标签的 issues，这些通常是： - -- 文档改进 -- 简单的 bug 修复 -- 代码格式化 -- 测试用例添加 - -## 🤔 获取帮助 - -### 沟通渠道 - -- **GitHub Issues**: 报告问题和功能请求 -- **Email**: 敏感问题可发送至维护者邮箱 - -### 常见问题 - -**Q: 如何添加新平台支持？** A: 在 `src/config/platform-catalog.js` -中添加平台地址；如果需要特殊路径转换，再更新 -`src/routing/platform-transformers.js`，然后补充相关文档和测试。 - -**Q: 如何测试 Cloudflare Workers 功能？** A: 使用 `npm run dev` -启动本地开发服务器，或部署到 Cloudflare Workers 测试环境。 - -**Q: 如何处理跨域问题？** A: 检查 CORS 配置，确保允许的源和方法设置正确。 - -## 📄 许可证 - -通过贡献代码，您同意您的贡献将在与存储库相同的 [AGPL-3.0 许可证](LICENSE) -下发布。 - -## 🙏 致谢 - -感谢所有为 Xget 做出贡献的开发者、测试者和用户。您的支持和反馈是存储库持续改进的动力！ - ---- - -如果您有任何问题或建议，请随时通过 GitHub Issues 与我们联系。我们期待您的参与！ +By participating in this project, you agree to follow +[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Please be respectful, assume good +intent, and help keep the project welcoming for users and contributors from a +wide range of backgrounds and experience levels. diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..d9371b2 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,70 @@ +# Governance + +## Governance model + +Xget currently follows a maintainer-led governance model. The project is still +small enough that a lightweight process works best, but decisions should remain +transparent and open to community input. + +## Current maintainer + +- [Xi Xu](https://xi-xu.com) + +The primary maintainer is responsible for project direction, releases, final +review decisions, security response coordination, and enforcement of the +[Code of Conduct](CODE_OF_CONDUCT.md). + +## Roles + +### Users + +Users rely on the project, report issues, request features, and help validate +behavior across environments. + +### Contributors + +Contributors improve the project through code, documentation, issue triage, +testing, design feedback, translations, operational guidance, or community +support. + +### Maintainers + +Maintainers are trusted contributors with additional responsibility for the +health of the project. Maintainers may review and merge changes, shape project +direction, manage releases, and coordinate responses to sensitive issues. + +## Decision-making + +- Day-to-day decisions are made through issues, pull requests, and maintainer + review +- Community input is encouraged for significant behavioral, API, governance, or + deployment changes +- Consensus is preferred when practical +- When consensus is unclear, the primary maintainer has final decision-making + authority + +## Becoming a maintainer + +Additional maintainers may be added as the project grows. The usual path is: + +1. Make sustained, high-quality contributions over time +2. Demonstrate good judgment, respectful collaboration, and project context +3. Help with review, issue triage, documentation, or support beyond code alone +4. Receive an invitation from the current maintainer + +There is no automatic threshold for maintainer access. Trust, consistency, and +care for the project matter more than contribution count alone. + +## Project direction and releases + +- The roadmap may evolve based on user needs, maintainer capacity, and platform + changes +- Maintainers may decline features that add long-term maintenance burden, reduce + security, or broaden the scope beyond the core mission of Xget +- Releases, backports, and support windows are managed on a best-effort basis + +## Transparency + +Important technical and product decisions should, whenever possible, be +documented in public issues, pull requests, or repository documentation so the +community can understand how the project is evolving. diff --git a/README.md b/README.md index 54f3cff..c8a5fbb 100644 --- a/README.md +++ b/README.md @@ -3055,6 +3055,12 @@ We welcome all forms of contribution! Please check the [Contributing Guide](CONTRIBUTING.md) to learn how to participate in repository development. +Community and maintainer expectations are documented in: + +- [Code of Conduct](CODE_OF_CONDUCT.md) +- [Security Policy](SECURITY.md) +- [Governance](GOVERNANCE.md) + 1. **Report Issues**: Use [issue templates](https://github.com/xixu-me/Xget/issues/new/choose) to report bugs or propose feature requests diff --git a/README.zh-Hans.md b/README.zh-Hans.md index 2b2960d..b8a7ae4 100644 --- a/README.zh-Hans.md +++ b/README.zh-Hans.md @@ -2923,6 +2923,12 @@ npx wrangler dev --log-level debug 我们欢迎各种形式的贡献！请查看[贡献指南](CONTRIBUTING.md)了解如何参与存储库开发。 +社区协作与维护者职责说明请参考： + +- [行为准则](CODE_OF_CONDUCT.md) +- [安全策略](SECURITY.md) +- [治理说明](GOVERNANCE.md) + 1. **报告问题**: 使用 [issue 模板](https://github.com/xixu-me/Xget/issues/new/choose)报告 bug 或提出功能请求 2. **提交代码**: fork 存储库，创建功能分支，提交 pull request diff --git a/README.zh-Hant.md b/README.zh-Hant.md index 970e3d4..7b3d111 100644 --- a/README.zh-Hant.md +++ b/README.zh-Hant.md @@ -2922,6 +2922,12 @@ npx wrangler dev --log-level debug 我們歡迎各種形式的貢獻！請檢視[貢獻指南](CONTRIBUTING.md)了解如何參與儲存庫開發。 +社群協作與維護者職責說明請參考： + +- [行為準則](CODE_OF_CONDUCT.md) +- [安全政策](SECURITY.md) +- [治理說明](GOVERNANCE.md) + 1. **報告問題**: 使用 [issue 範本](https://github.com/xixu-me/Xget/issues/new/choose)報告 bug 或提出功能請求 2. **提交程式碼**: fork 儲存庫，建立功能分支，提交 pull request diff --git a/SECURITY.md b/SECURITY.md index 8d5786d..30c1efb 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,146 +1,64 @@ -# 安全政策 +# Security Policy -## 🚨 报告安全漏洞 +Xget proxies requests across code hosting platforms, package registries, +container registries, and AI inference providers. If you believe you have found +a security vulnerability, please report it responsibly and avoid public +disclosure until maintainers have had a chance to investigate. -如果您发现了安全漏洞，请**不要**通过公开的 GitHub Issues 报告。相反，请通过以下方式私下联系我们： +## Supported versions -### 联系方式 +Security fixes are developed against the latest code on `main`. Backports to +older revisions or downstream forks are not guaranteed. -- **邮箱**: -- **主题**: [SECURITY] Xget 安全漏洞报告 +| Version | Supported | +| ------------------------------ | ---------------- | +| `main` | Yes | +| Older commits, tags, and forks | Best effort only | -### 报告内容 +## How to report a vulnerability -请在报告中包含以下信息： +Please do not open a public GitHub issue for suspected vulnerabilities. -1. **漏洞描述**: 详细描述发现的安全问题 -2. **影响范围**: 说明漏洞可能造成的影响 -3. **重现步骤**: 提供详细的重现步骤 -4. **环境信息**: 包括平台、配置、运行环境等 -5. **建议修复**: 如果有修复建议请一并提供 +Instead, use one of these private channels: -### 响应时间 +1. GitHub private vulnerability reporting for this repository, if it is enabled +2. The maintainer contact page at -- **确认收到**: 24 小时内 -- **初步评估**: 72 小时内 -- **详细分析**: 7 天内 -- **修复交付**: 根据严重程度，通常在 14-30 天内 +Please include as much of the following as you can: -## 🛡️ 安全特性 +- A clear description of the vulnerability +- The affected code path, route shape, platform prefix, or deployment flow +- Reproduction steps or a proof of concept +- Impact assessment, including confidentiality, integrity, or availability + concerns +- Any suggested remediation, if you have one +- Sanitized logs, headers, or payload samples with secrets removed -### 传输安全 +## What to expect -- **强制 HTTPS**: 所有通信均通过 HTTPS 加密 -- **HSTS 头**: 防止协议降级攻击 -- **安全传输**: 使用现代 TLS 协议 +- Maintainers will acknowledge reports on a best-effort basis +- Reports will be reviewed privately and handled confidentially where possible +- Maintainers may ask follow-up questions to validate severity and scope +- If the report is confirmed, maintainers will work toward a fix and coordinate + a disclosure timeline -### 请求安全 +## Scope notes -- **方法限制**: 严格的 HTTP 方法白名单 -- **路径验证**: 防止路径遍历攻击 -- **长度限制**: URL 长度限制防止缓冲区溢出 -- **超时保护**: 30 秒请求超时防止资源耗尽 +The following are usually in scope: -### 内容安全 +- Vulnerabilities in Xget source code +- Security weaknesses in official deployment manifests or adapters +- Authentication, header forwarding, request validation, cache isolation, and + secret handling issues -- **CSP 头**: 严格的内容安全策略 -- **XSS 防护**: 内置跨站脚本攻击防护 -- **点击劫持防护**: X-Frame-Options 头防止嵌入 -- **引用策略**: 控制 HTTP 引用信息 +The following are usually out of scope unless Xget directly introduces them: -### 输入验证 +- Availability-only complaints caused by third-party outages +- Misconfiguration in self-hosted deployments outside the repository defaults +- Issues in upstream services that Xget only proxies -- **参数清理**: 所有输入参数严格验证 -- **编码处理**: 正确的字符编码处理 -- **注入防护**: 防止各类注入攻击 +## Handling sensitive information -## 🔍 安全最佳实践 - -### 部署安全 - -1. **环境隔离**: 生产环境与开发环境严格分离 -2. **访问控制**: 最小权限原则 -3. **监控日志**: 启用详细的安全日志记录 -4. **定期更新**: 及时更新依赖和运行时 - -### 配置安全 - -1. **敏感信息**: 使用环境变量存储敏感配置 -2. **CORS 设置**: 合理配置跨域资源共享 -3. **缓存策略**: 避免缓存敏感信息 -4. **错误处理**: 不暴露内部实现细节 - -### 使用安全 - -1. **域名验证**: 确保使用可信的部署域名 -2. **定期检查**: 定期检查服务状态和日志 -3. **依赖更新**: 及时更新依赖和运行时环境 -4. **备份恢复**: 建立完善的备份和恢复机制 - -## 📋 安全检查清单 - -### 部署前检查 - -- [ ] 所有依赖项已更新到安全版本 -- [ ] 安全头配置正确 -- [ ] 环境变量配置安全 -- [ ] CORS 策略配置合理 -- [ ] 日志记录已启用 - -### 运行时监控 - -- [ ] 异常请求监控 -- [ ] 性能指标监控 -- [ ] 错误率监控 -- [ ] 资源使用监控 - -### 定期维护 - -- [ ] 依赖项安全扫描 -- [ ] 代码安全审计 -- [ ] 配置安全检查 -- [ ] 日志分析 - -## 🚀 安全更新 - -### 更新通知 - -安全更新将通过以下渠道同步： - -- 存储库 README -- 安全公告邮件（如适用） - -### 更新优先级 - -- **严重**: 立即更新 -- **高**: 24 小时内更新 -- **中**: 7 天内更新 -- **低**: 下次常规更新 - -## 🤝 安全贡献 - -### 安全研究 - -我们欢迎负责任的安全研究，包括： - -- 代码审计 -- 渗透测试 -- 漏洞发现 -- 安全改进建议 - -### 致谢 - -我们将在适当的地方公开感谢报告安全问题的研究人员（除非他们要求匿名）。 - -## 📞 紧急联系 - -对于严重的安全问题，请立即联系： - -- **邮箱**: -- **主题**: [URGENT SECURITY] 紧急安全问题 - -我们承诺在收到紧急安全报告后 12 小时内响应。 - ---- - -感谢您帮助保持 Xget 的安全性！ +Do not include private tokens, credentials, or other secrets in public issues, +pull requests, or discussion threads. If a proof of concept requires secrets, +share them only through a private reporting channel and rotate them afterward. diff --git a/adapters/functions/api/index.js b/adapters/functions/api/index.js index 90df507..133a6fc 100644 --- a/adapters/functions/api/index.js +++ b/adapters/functions/api/index.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/adapters/functions/deno.js b/adapters/functions/deno.js index 0f7134c..fd77d15 100644 --- a/adapters/functions/deno.js +++ b/adapters/functions/deno.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/adapters/functions/netlify/edge-functions/edge-handler.js b/adapters/functions/netlify/edge-functions/edge-handler.js index 0e4fd9e..a759a8d 100644 --- a/adapters/functions/netlify/edge-functions/edge-handler.js +++ b/adapters/functions/netlify/edge-functions/edge-handler.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by @@ -20,4 +20,3 @@ * source of truth at /api/index.js. */ export { config, default } from '../../api/index.js'; - diff --git a/adapters/pages/functions/[[path]].js b/adapters/pages/functions/[[path]].js index fc8cbb9..771b31e 100644 --- a/adapters/pages/functions/[[path]].js +++ b/adapters/pages/functions/[[path]].js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/skills/xget/scripts/xget.mjs b/skills/xget/scripts/xget.mjs index a27e148..5b22646 100644 --- a/skills/xget/scripts/xget.mjs +++ b/skills/xget/scripts/xget.mjs @@ -1,5 +1,3 @@ -#!/usr/bin/env node - import { get } from 'node:https'; import { relative } from 'node:path'; import process from 'node:process'; diff --git a/src/app/handle-request.js b/src/app/handle-request.js index 6c20365..5c7f78a 100644 --- a/src/app/handle-request.js +++ b/src/app/handle-request.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by @@ -8,19 +8,19 @@ * (at your option) any later version. */ -import { createRequestContext } from './request-context.js'; +import { handleDockerAuth } from '../protocols/docker.js'; +import { finalizeResponse } from '../response/finalize-response.js'; import { createHomepageRedirect, normalizeEffectivePath, resolveTarget } from '../routing/resolve-target.js'; -import { finalizeResponse } from '../response/finalize-response.js'; -import { handleDockerAuth } from '../protocols/docker.js'; import { getDefaultCache, tryReadCachedResponse } from '../upstream/cache.js'; import { fetchUpstreamResponse } from '../upstream/fetch-upstream.js'; import { PerformanceMonitor, addPerformanceHeaders } from '../utils/performance.js'; import { addCorsHeaders, addSecurityHeaders, createErrorResponse } from '../utils/security.js'; import { getAllowedMethods, isProtocolRequest, validateRequest } from '../utils/validation.js'; +import { createRequestContext } from './request-context.js'; /** * Main request handler with comprehensive caching, retry logic, and security measures. diff --git a/src/config/index.js b/src/config/index.js index ae61b76..2789798 100644 --- a/src/config/index.js +++ b/src/config/index.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/config/platform-catalog.js b/src/config/platform-catalog.js index a5a88ec..89e493a 100644 --- a/src/config/platform-catalog.js +++ b/src/config/platform-catalog.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/index.js b/src/index.js index 1e0398d..0a1d3d2 100644 --- a/src/index.js +++ b/src/index.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/protocols/ai.js b/src/protocols/ai.js index bcff88e..2213eda 100644 --- a/src/protocols/ai.js +++ b/src/protocols/ai.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/protocols/docker.js b/src/protocols/docker.js index c058ab3..72661dc 100644 --- a/src/protocols/docker.js +++ b/src/protocols/docker.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/protocols/git.js b/src/protocols/git.js index 0333740..6aa098d 100644 --- a/src/protocols/git.js +++ b/src/protocols/git.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/protocols/huggingface.js b/src/protocols/huggingface.js index e1a76d0..d0ec64e 100644 --- a/src/protocols/huggingface.js +++ b/src/protocols/huggingface.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/utils/performance.js b/src/utils/performance.js index cad22ba..c8cf304 100644 --- a/src/utils/performance.js +++ b/src/utils/performance.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/utils/security.js b/src/utils/security.js index 8d5e995..e1b479d 100644 --- a/src/utils/security.js +++ b/src/utils/security.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by diff --git a/src/utils/validation.js b/src/utils/validation.js index fa04c1a..4f03ab2 100644 --- a/src/utils/validation.js +++ b/src/utils/validation.js @@ -1,6 +1,6 @@ /** * Xget - High-performance acceleration engine for developer resources - * Copyright (C) 2025 Xi Xu + * Copyright (C) Xi Xu * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by