🗽 Sync 2026-10-23 00:46:23

luci-theme-argon/docs/DEVELOPMENT.md

@@ -17,6 +17,10 @@ make package/luci-theme-argon/compile V=s
 
 Theme settings are included. Select the nested `compat/luci-app-argon-config` package under LuCI applications only when building the migration package. Existing translation names remain `luci-i18n-argon-config-*`.
 
+Firmware and GitHub Actions build scripts should stop cloning the old standalone `luci-app-argon-config` repository and deselect that plugin. The old `1.0-r20261008` plugin duplicates the configuration, RPC services, settings page and icons now owned by the theme, causing APK's `trying to overwrite ... owned by luci-theme-argon` errors. New firmware only needs the theme. If the old package name is required, use this repository's empty migration package and keep exactly one definition of that package in the build tree. After updating an existing build tree, run `make defconfig` and clean the old plugin's build outputs before rebuilding.
+
+The older `does not support ucode template precompilation` log line is LuCI's skip message, separate from the file conflict. This package disables precompilation and ships `.ut` source to avoid SDK/target ucode bytecode incompatibilities; other LuCI packages can retain precompilation.
+
 Release CI builds IPK with the OpenWrt 23.05.5 SDK and APK v3 with the 25.12.5 SDK. Ucode templates ship as source to avoid tying packages to one runtime's bytecode format.
 
 Translations use `PKG_PO_VERSION` to follow the theme release, including `-r<revision>` for APK. IPK translations retain a `v` prefix (for example, `v3.0.1`) so ordinary installation upgrades the broken v3.0.0 `unknown` version. Keep that prefix in future IPK releases. CI reads each translation's internal package metadata and blocks artifact upload and publication if the version is wrong.
@@ -87,6 +91,46 @@ Top-level menu nodes resolve `htdocs/luci-static/argon/icon/<node-name>.svg`, in
 
 Use monochrome SVGs with a `viewBox` and transparent background. CSS masks supply theme and interaction colors. Shared chevrons use the same 24×24 grid and 2px round strokes. See the [icon index](../htdocs/luci-static/argon/icon/README.md) for available assets. This mechanism is separate from uploaded browser icons and login logos.
 
+## Static update feed deployment
+
+The router reads a static `/updates/stable.json` manifest without calling the GitHub API. After publication, CI uses its own `GITHUB_TOKEN` to retrieve the official release, verifies the theme package SHA256 digests and sizes, and generates one artifact. GitHub Pages publishes that artifact directly; Cloudflare Pages deploys the same files from a dedicated `updates` Git branch. Packages continue to download from the pinned GitHub Release, and translation packages remain separate.
+
+Initial maintainer setup:
+
+1. Set **Settings → Pages → Build and deployment → Source** to **GitHub Actions**. Allow the default branch and release tags in the `github-pages` environment. The workflow needs `contents: write` to publish the `updates` branch.
+2. Once this code is on the default branch, manually run **Publish update feeds**. This initializes GitHub Pages and creates the `updates` branch from the latest stable release, without publishing a new version or requiring CF setup first.
+3. Create a Cloudflare Pages **Git integration** project connected to this GitHub repository. Set production branch to `updates`, framework to **None**, build command to `exit 0`, output directory to `.`, and preview branches to **None**. Use the assigned `pages.dev` hostname or your own domain. Existing Direct Upload projects need to be replaced with a new Git integration project.
+4. Set these repository **Variables** under **Settings → Secrets and variables → Actions**:
+
+   | Variable | Value |
+   | --- | --- |
+   | `ARGON_UPDATE_PRIMARY_URL` | Complete URL, e.g. `https://<assigned-hostname>/updates/stable.json` |
+   | `ARGON_UPDATES_ENABLED` | `true` to synchronize after stable releases |
+   | `ARGON_UPDATE_FALLBACK_URL` | Optional; defaults to `https://jerrykuku.github.io/luci-theme-argon/updates/stable.json`. Override for a custom fallback domain. |
+
+5. Choose how CF is triggered. By default, keep automatic production branch deployments enabled: pushing `updates` triggers CF without a CF secret in GitHub. For Deploy Hooks, create a hook bound to `updates` under CF **Settings → Builds → Add deploy hook**. Save the complete URL as the GitHub repository Actions **Secret** `CF_PAGES_DEPLOY_HOOK`, then disable **Enable automatic production branch deployments** to avoid building each publication twice.
+6. Compare `/updates/stable.json` on both hosts byte for byte. Verify primary access, fallback access and actual package downloads from the target router's network. New release packages embed the configured source URLs; changing repository variables does not change themes already installed on devices.
+
+`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_PAGES_PROJECT` are no longer used. The Hook URL contains its own trigger credential and belongs in a Secret. A successful Hook response means CF accepted the build request; check Pages for the actual deployment result.
+
+Only successful stable publications update the feed. Previews are excluded, and a delayed old-release job skips publication when its tag is no longer Latest. The `updates` branch contains generated static files, preserves commit history and rejects conflicting pushes. The publisher refuses to overwrite an existing unrelated branch with that name.
+
+Run **Publish update feeds** again to republish GitHub Pages. Identical artifacts do not create another branch commit. With a Hook configured, reruns still trigger CF when the branch is unchanged, allowing failed deployments to be retried. With Git auto-deployment only, retry the build in CF or publish changed feed content. Both publication jobs are independent, so either side can publish if the other fails.
+
+The manifest contains `schema`, `repository`, `tag`, `published_at`, `notes`, and the `apk`/`ipk` filenames with `_sha256`/`_size` fields. Metadata comes from the published package bytes rather than master's Makefile. Both formats must be complete and match the tag. Malformed feeds trigger fallback and never overwrite the previous successful cache. Checks are manual, with a five-minute success cache, a one-minute failure cooldown and a lock that coalesces concurrent requests.
+
+Source builds default to an empty CF primary. Configure one before packaging:
+
+```sh
+python3 .github/scripts/generate_update_site.py sources \
+  --primary 'https://YOUR_DOMAIN/updates/stable.json' \
+  --output root/usr/share/argon/update-sources.json
+```
+
+Sources must be complete HTTPS URLs without credentials, ports, query strings or fragments. Runtime sources live in `/usr/share/argon/update-sources.json`, which is updated by theme packages separately from `/etc/config/argon`. The installer constructs fixed official release download URLs; manifests cannot supply arbitrary download URLs.
+
+References: [Cloudflare GitHub integration](https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/), [Deploy Hooks](https://developers.cloudflare.com/pages/configuration/deploy-hooks/), [branch deployment controls](https://developers.cloudflare.com/pages/configuration/branch-build-controls/), [custom GitHub Pages workflows](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages).
+
 ## Checks
 
 Use Node.js 22+, Python 3, LESS 4.1.3 and a Ucode build matching the supported OpenWrt runtime:

luci-theme-argon/docs/DEVELOPMENT_ZH.md

@@ -17,6 +17,10 @@ make package/luci-theme-argon/compile V=s
 
 主题设置已内置。仅在需要构建旧插件迁移包时，在 LuCI 应用中额外选择嵌套的 `compat/luci-app-argon-config` 包。语言包继续使用 `luci-i18n-argon-config-*` 名称。
 
+固件或 GitHub Actions 构建脚本应移除旧版独立 `luci-app-argon-config` 仓库的克隆步骤，并取消旧插件选项。旧版 `1.0-r20261008` 插件会重复安装主题已内置的配置、RPC、设置页及图标，导致 APK 报 `trying to overwrite ... owned by luci-theme-argon`。新固件只需选择主题；需要保留旧包名时，使用本仓库的空迁移包，整个构建树中只保留一份该包定义。已有构建缓存时，更新包定义后重新运行 `make defconfig`，并清理旧插件的编译产物再编译。
+
+旧构建日志中的 `does not support ucode template precompilation` 是 LuCI 的跳过提示，不是上述文件冲突的原因。本包关闭模板预编译并保留 `.ut` 源码，避免 SDK 与目标设备的 ucode 字节码格式不一致；无需关闭其他 LuCI 包的预编译。
+
 发行 CI 使用 OpenWrt 23.05.5 SDK 构建 IPK、25.12.5 SDK 构建 APK v3。Ucode 模板保留源码，避免绑定某个运行时的字节码格式。
 
 语言包通过 `PKG_PO_VERSION` 跟随主题发行版本，APK 包含 `-r<修订号>`。IPK 语言包固定使用 `v` 前缀（如 `v3.0.1`），使已安装的 v3.0.0 `unknown` 语言包可以直接正常升级；后续版本须保留该前缀。发布前会逐个读取语言包内部元数据，版本不符时阻止上传和发布。
@@ -87,6 +91,46 @@ lessc less/cascade.less htdocs/luci-static/argon/css/cascade.css
 
 使用透明背景、带 `viewBox` 的单色 SVG，CSS mask 负责主题与交互颜色。共享箭头使用 24×24 网格、2px 圆角描边。资源见 [SVG 图标索引](../htdocs/luci-static/argon/icon/README.md)，与用户上传的网站图标 / 登录 Logo 独立。
 
+## 静态更新源部署
+
+更新检查读取 `/updates/stable.json` 静态清单。路由器不调用 GitHub API；发布工作流使用自身的 `GITHUB_TOKEN` 读取正式 Release，核验主题包的 SHA256/大小后生成一份产物。GitHub Pages 直接发布该产物，Cloudflare Pages 从专用 `updates` 分支部署同一份文件。安装包继续从固定的 GitHub Release 版本下载，独立语言包仍单独安装。
+
+首次启用需要仓库维护者完成以下配置：
+
+1. 在仓库 **Settings → Pages → Build and deployment → Source** 选择 **GitHub Actions**。`github-pages` 环境的部署规则需允许默认分支和正式发布标签；工作流需要 `contents: write` 权限来更新 `updates` 分支。
+2. 本次代码进入默认分支后，在 Actions 手动运行 **Publish update feeds**。它会用当前最新正式版初始化 GitHub Pages，并创建 `updates` 分支，无需发布新版本，也无需先配置 CF。
+3. 在 Cloudflare 创建 **Git 集成**类型的 Pages 项目，连接本 GitHub 仓库。生产分支选 `updates`，框架选 **None**，构建命令填 `exit 0`，输出目录填 `.`，预览分支选 **None**。记录实际分配的 `pages.dev` 地址，或绑定自己控制的域名。如果之前创建了 Direct Upload 项目，需要新建 Git 集成项目。
+4. 在仓库 **Settings → Secrets and variables → Actions → Variables** 设置：
+
+   | 仓库变量 | 值 |
+   | --- | --- |
+   | `ARGON_UPDATE_PRIMARY_URL` | 完整主源地址，例如 `https://<实际项目地址>/updates/stable.json` |
+   | `ARGON_UPDATES_ENABLED` | `true`，启用正式发布后的自动同步 |
+   | `ARGON_UPDATE_FALLBACK_URL` | 可选；默认 `https://jerrykuku.github.io/luci-theme-argon/updates/stable.json`。备用源绑定自有域名时设置。 |
+
+5. 选择 CF 的触发方式。默认保留生产分支自动部署，发布工作流推送 `updates` 后 CF 自动构建，GitHub 无需 CF Secret。若要使用 Deploy Hook，在 CF 的 **Settings → Builds → Add deploy hook** 创建绑定 `updates` 分支的 Hook，将完整 URL 保存为 GitHub 仓库 Actions **Secret** `CF_PAGES_DEPLOY_HOOK`，并关闭 CF 的 **Enable automatic production branch deployments**，避免同一次发布构建两次。
+6. 读取两端 `/updates/stable.json`，核对内容完全相同；在目标路由器网络验证主源读取、主源失败后的备用读取，以及真实包下载。配置生效后构建的新安装包会带上主源地址；设置仓库变量不会改变已经安装在设备上的主题。
+
+此方案不再使用 `CLOUDFLARE_API_TOKEN`、`CLOUDFLARE_ACCOUNT_ID` 或 `CLOUDFLARE_PAGES_PROJECT`。Hook URL 本身包含触发凭据，只存入 Secret。Hook 返回成功表示 CF 已接受构建请求，实际部署结果需在 CF Pages 查看。
+
+发布工作流仅在正式 Release 成功后自动同步。预发布版本不进入稳定清单；延迟执行的旧版本任务发现自己已不是 Latest 时跳过。`updates` 分支只保存生成的静态文件，保留提交历史并拒绝冲突推送；如果同名分支已用于其他用途，脚本会停止而不覆盖。
+
+重新运行 **Publish update feeds** 可再次发布 GitHub Pages；清单未变化时不重复创建分支提交。若配置了 Hook，即使分支内容未变化也会重新触发 CF，便于重试失败的部署；仅使用 Git 自动部署时，需要在 CF 中重试构建或新增清单提交。两端发布任务互相独立，一端失败不会阻止另一端发布。
+
+清单字段包括 `schema`、`repository`、`tag`、`published_at`、`notes`，以及 `apk`/`ipk` 文件名和对应的 `_sha256`/`_size`。由最终发布包计算元数据，不从 master 的 Makefile 推断最新版。两种格式均须完整且属于同一版本；客户端拒绝损坏清单，并保留上一次成功记录。请求只在手动检查时发起，成功缓存五分钟，双源均失败后冷却一分钟。
+
+源码构建默认不包含 CF 地址。需要自行指定时，在打包前执行：
+
+```sh
+python3 .github/scripts/generate_update_site.py sources \
+  --primary 'https://YOUR_DOMAIN/updates/stable.json' \
+  --output root/usr/share/argon/update-sources.json
+```
+
+主备地址须为完整 HTTPS URL，不含凭据、端口、查询参数或片段。路由器端配置位于 `/usr/share/argon/update-sources.json`；下载地址由安装器固定构造，清单不能指定任意包下载 URL。此目录的配置不属于 `/etc/config/argon` 用户设置，后续主题安装包会更新它。
+
+参考：[Cloudflare GitHub 集成](https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/)、[Deploy Hooks](https://developers.cloudflare.com/pages/configuration/deploy-hooks/)、[分支部署控制](https://developers.cloudflare.com/pages/configuration/branch-build-controls/)、[GitHub Pages 自定义工作流](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)。
+
 ## 检查
 
 准备 Node.js 22+、Python 3、LESS 4.1.3，以及与目标 OpenWrt 运行时匹配的 Ucode：