chore: sync main with upstream Wei-Shaw/sub2api

.dockerignore

@@ -11,6 +11,11 @@
 *.md
 !deploy/DOCKER.md
 docs/
+# admin-compliance gate (LegalDocumentView.vue) build-time imports
+# docs/legal/*.md?raw into the frontend bundle; keep that subtree in the
+# Docker build context even though docs/ is otherwise excluded.
+!docs/legal/
+!docs/legal/*.md
 
 # IDE
 .idea/
@@ -44,6 +49,9 @@ coverage/
 .env.*
 !.env.example
 
+# 本地闭源插件目录可能包含发布签名私钥，绝不能进入 Docker 构建上下文。
+/plugins/
+
 # Local config
 config.yaml
 config.local.yaml

.github/SECURITY.md

@@ -0,0 +1,107 @@
+# Security Policy
+
+[English](#english) | [中文](#中文)
+
+## English
+
+### Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues, pull requests, or discussions.**
+
+Report them privately through GitHub's private vulnerability reporting:
+
+**[Report a vulnerability](https://github.com/Wei-Shaw/sub2api/security/advisories/new)**
+
+(Repository → **Security** tab → **Report a vulnerability**.) Only the maintainers can see the report, and the advisory becomes the place to discuss, fix, and eventually publish the issue.
+
+If you cannot use GitHub private vulnerability reporting, email **dev@sub2api.org** instead, with `[Security]` in the subject line.
+
+A useful report includes:
+
+- The affected component and version (release tag or commit)
+- Impact: what an attacker can do and which privileges they need
+- Minimal reproduction steps or a proof of concept
+- Any non-default configuration required to trigger the issue
+- A suggested fix, if you have one
+
+### Supported Versions
+
+Sub2API releases frequently, and fixes ship in a new release rather than being backported.
+
+| Version | Supported |
+| ------- | --------- |
+| Latest release | ✅ |
+| Older releases | ❌ |
+
+Please confirm that the issue reproduces on the latest release or on `main` before reporting.
+
+### Scope
+
+In scope: the Sub2API backend, frontend, official Docker images, and deployment files in this repository.
+
+Usually out of scope:
+
+- Issues that require already-compromised admin credentials or server access
+- Risks arising from explicitly weakening documented security settings (for example, disabling `security.url_allowlist`)
+- Vulnerabilities in upstream AI providers or third-party dependencies with no Sub2API-specific impact (please report those upstream)
+- Missing best-practice headers or scanner output without a demonstrated impact
+
+### Disclosure Process
+
+1. We acknowledge the report and assess its validity and severity.
+2. We develop a fix privately in the advisory and may ask you to verify it.
+3. We publish a release containing the fix, then publish the GitHub Security Advisory (with a CVE when applicable), crediting you unless you prefer to stay anonymous.
+
+Please keep details private until the advisory is published. This is a volunteer-maintained project, so response times are best effort.
+
+## 中文
+
+### 报告漏洞
+
+**请不要通过公开的 Issue、Pull Request 或 Discussion 报告安全漏洞。**
+
+请使用 GitHub 私密漏洞报告功能提交：
+
+**[提交漏洞报告](https://github.com/Wei-Shaw/sub2api/security/advisories/new)**
+
+（仓库 → **Security** 标签页 → **Report a vulnerability**。）报告仅维护者可见，后续的讨论、修复与公告发布都在该安全公告中进行。
+
+如果无法使用 GitHub 私密漏洞报告，也可以发送邮件至 **dev@sub2api.org**，邮件标题请注明 `[Security]`。
+
+报告中建议包含：
+
+- 受影响的组件与版本（Release tag 或 commit）
+- 影响：攻击者能做什么、需要什么权限
+- 最小复现步骤或 PoC
+- 触发问题所需的非默认配置
+- 修复建议（如有）
+
+### 支持的版本
+
+Sub2API 发版频繁，安全修复随新版本发布，不向旧版本回移。
+
+| 版本 | 是否支持 |
+| ---- | -------- |
+| 最新 Release | ✅ |
+| 更早的版本 | ❌ |
+
+报告前请先确认问题在最新 Release 或 `main` 上仍可复现。
+
+### 范围
+
+范围内：本仓库中的 Sub2API 后端、前端、官方 Docker 镜像与部署文件。
+
+通常不在范围内：
+
+- 需要事先已掌握管理员凭据或服务器权限才能利用的问题
+- 因主动关闭文档中的安全配置（如关闭 `security.url_allowlist`）而产生的风险
+- 上游 AI 服务商或第三方依赖自身的漏洞，且对 Sub2API 无特定影响（请向上游报告）
+- 仅缺少最佳实践响应头或扫描器输出，但未证明实际影响
+
+### 披露流程
+
+1. 我们确认收到报告，并评估其有效性与严重程度。
+2. 我们在安全公告中私下开发修复，可能请你协助验证。
+3. 我们先发布包含修复的版本，再公开 GitHub 安全公告（适用时申请 CVE），并致谢报告者（如你希望匿名则不署名）。
+
+在公告发布前请勿公开漏洞细节。本项目由志愿者维护，响应时间尽力而为。

.github/audit-exceptions.yml

@@ -3,16 +3,16 @@ exceptions:
   - package: xlsx
     advisory: "GHSA-4r6h-8v6p-xvw6"
     severity: high
-    reason: "Admin export only; switched to dynamic import to reduce exposure (CVE-2023-30533)"
-    mitigation: "Load only on export; restrict export permissions and data scope"
-    expires_on: "2026-07-06"
+    reason: "Write-only: admin UsageView lazily imports xlsx solely for XLSX.write export; the advisory requires parsing a crafted file and no XLSX.read path exists (CVE-2023-30533)"
+    mitigation: "Never parse untrusted spreadsheets with xlsx; no patched version on npm, migrate to SheetJS CDN build or another writer before expiry"
+    expires_on: "2027-01-06"
     owner: "security@your-domain"
   - package: xlsx
     advisory: "GHSA-5pgg-2g8v-p4x9"
     severity: high
-    reason: "Admin export only; switched to dynamic import to reduce exposure (CVE-2024-22363)"
-    mitigation: "Load only on export; restrict export permissions and data scope"
-    expires_on: "2026-07-06"
+    reason: "Write-only: admin UsageView lazily imports xlsx solely for XLSX.write export; the advisory requires parsing a crafted file and no XLSX.read path exists (CVE-2024-22363)"
+    mitigation: "Never parse untrusted spreadsheets with xlsx; no patched version on npm, migrate to SheetJS CDN build or another writer before expiry"
+    expires_on: "2027-01-06"
     owner: "security@your-domain"
   - package: lodash
     advisory: "GHSA-r5fr-rjxr-66jc"
@@ -35,3 +35,10 @@ exceptions:
     mitigation: "Proxy configuration not user-controlled; upgrade when axios releases fix"
     expires_on: "2026-07-10"
     owner: "security@your-domain"
+  - package: nanoid
+    advisory: "GHSA-2v37-7h3g-55p8"
+    severity: high
+    reason: "Custom generator with size=0 not used; all nanoid calls use default size or positive values"
+    mitigation: "No zero-size custom generators in codebase; upgrade when nanoid releases fix"
+    expires_on: "2026-10-13"
+    owner: "security@your-domain"

.github/release-tools/.gitignore

@@ -0,0 +1 @@
+__pycache__/

.github/release-tools/README.md

@@ -0,0 +1,30 @@
+# Release matrix
+
+The release workflow builds the frontend once, then runs each configured Go target on its own Linux runner. `CGO_ENABLED=0` permits cross-compilation. The target matrix is read from `.goreleaser.yaml`, including its exclusions; simple releases select Linux amd64 only.
+
+Each build uses GoReleaser OSS in snapshot mode with the selected release version and one target. Archive naming, bundled files, Go flags and release templates remain in the existing GoReleaser configurations. Every archive is accompanied by its source commit, target, version and SHA256. The publishing job verifies the complete matrix before building images or publishing. It uses GoReleaser's `extra_files` support to publish existing archives and checksums, with builds disabled. No Pro license is needed.
+
+Go caches are isolated by target and refreshed on each source commit, with fallback to the preceding target cache. Save uses the original restore key, even if a build hook changes `go.sum`. Matrix jobs upload uniquely named artifacts. The publishing job extracts only the regular Linux binary from each verified archive and restores its executable permission before constructing Docker contexts. QEMU remains limited to runtime-image instructions. DockerHub images are omitted when its credentials are absent; GHCR is always retained. Simple mode still publishes only the amd64 GHCR image and the simple release description.
+
+All build jobs use the commit resolved by `prepare`, including a manual release's selected tag. Helper scripts come from the workflow revision and are passed as a run-local artifact, so older application tags do not need to contain the new scripts. The workflow serializes release runs to prevent simultaneous updates to moving image tags.
+
+## Validate without publication
+
+From a branch containing this workflow:
+
+```bash
+gh workflow run release.yml --ref <branch> \
+  -f tag=<branch> -f dry_run=true -f simple_release=false
+```
+
+A dry run builds all selected archives and both runtime images, verifies artifact provenance and produces the final checksum file. It exports images locally as OCI archives instead of pushing them. It skips registry logins, GitHub Release publication, DockerHub description updates, Telegram notifications and VERSION synchronization. Test the simple path separately with `simple_release=true`.
+
+Dry-run artifacts are available in the Actions run, including `release-dry-run-report`. Compare job start/end times, GoReleaser's build duration and cache restore results. Do not present an initial cold-cache run as a warmed-cache benchmark; publishing network time is not measured by dry runs.
+
+Helper checks:
+
+```bash
+python -m pip install -r .github/release-tools/requirements-release.txt
+python -m unittest discover -s .github/release-tools -p 'test_release_matrix.py'
+bash -n .github/release-tools/release-images.sh
+```

.github/release-tools/release-images.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+: "${RELEASE_VERSION:?}" "${RELEASE_SHA:?}" "${GITHUB_REPOSITORY:?}" "${RUNNER_TEMP:?}"
+owner=${GITHUB_REPOSITORY%%/*}
+registries=("ghcr.io/${owner,,}/sub2api")
+if [[ ${SIMPLE_RELEASE:-false} != true && ${DOCKERHUB_USERNAME:-skip} != skip ]]; then
+  registries+=("${DOCKERHUB_USERNAME}/sub2api")
+fi
+arches=(amd64 arm64)
+if [[ ${SIMPLE_RELEASE:-false} == true ]]; then arches=(amd64); fi
+for arch in "${arches[@]}"; do
+  args=(--platform "linux/$arch" --file ".release-context/$arch/Dockerfile"
+    --label "org.opencontainers.image.version=$RELEASE_VERSION"
+    --label "org.opencontainers.image.revision=$RELEASE_SHA"
+    --label "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY")
+  for registry in "${registries[@]}"; do
+    args+=(--tag "$registry:$RELEASE_VERSION-$arch")
+    if [[ ${SIMPLE_RELEASE:-false} == true ]]; then
+      args+=(--tag "$registry:$RELEASE_VERSION" --tag "$registry:latest")
+    fi
+  done
+  if [[ ${DRY_RUN:-false} == true ]]; then
+    args+=(--output "type=oci,dest=$RUNNER_TEMP/sub2api-$arch.oci.tar")
+  else
+    args+=(--push)
+  fi
+  docker buildx build "${args[@]}" ".release-context/$arch"
+done
+if [[ ${DRY_RUN:-false} != true && ${SIMPLE_RELEASE:-false} != true ]]; then
+  major=${RELEASE_VERSION%%.*}
+  minor=${RELEASE_VERSION#*.}; minor=${minor%%.*}
+  for registry in "${registries[@]}"; do
+    docker buildx imagetools create \
+      --tag "$registry:$RELEASE_VERSION" --tag "$registry:latest" \
+      --tag "$registry:$major.$minor" --tag "$registry:$major" \
+      "$registry:$RELEASE_VERSION-amd64" "$registry:$RELEASE_VERSION-arm64"
+  done
+fi