Wekan PWA 安装与打包实战：将开源 Kanban 以应用形态部署到桌面与移动端

Wekan PWA 安装与打包实战将开源 Kanban 以应用形态部署到桌面与移动端【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekanWekan 是基于 Meteor 的开源看板Kanban系统其 Web 端本身即是一个标准 PWAProgressive Web App通过site.webmanifest声明应用清单配合一个“占位式”Service Worker让主流浏览器可以把登录页“安装”为独立应用。本篇以 docs/Browsers/PWA.md 为主干完整讲解在 Windows、iOS、Android 各浏览器上安装 Wekan 应用的步骤并深入仓库源码解析其 PWA 底层的 manifest 注册、Service Worker 逻辑、以及“全屏 Android 应用 Caddy assetlinks.json”的进阶打包方案适合自托管 Wekan 的管理员与希望发布 Android/Windows 商店应用的团队阅读。PWA 支持前提与适用版本以下操作中的 “Navigate to login page of Wekan” 即你的 Wekan 服务器登录页例如https://wekan.yourcompany.com/sign-in。安装为应用后桌面/主屏会出现 Wekan 应用图标应用以独立窗口运行不显示浏览器地址栏等 Web 浏览器控件。该能力在Wekan v4.02 及更新版本中可用。浏览器兼容性矩阵见 docs/Browsers/Browser-compatibility-matrix.md其中明确列出各浏览器的 PWA 支持情况如 Safari iOS Yes、Chrome/Chromium/Brave/Vivaldi/Opera Android Yes、Firefox No 等可作为安装前的兼容性核对依据。各平台安装 Wekan 应用的分步指南Windows 桌面Chromium Edge打开 Chromium Edge。导航到 Wekan 登录页。点击右上角⋮菜单选择“将站点安装为应用Install site as app”该菜单可用于安装、管理与卸载应用在弹出窗口中为应用命名例如YourCompany WeKan点击Add。安装完成后新应用会出现在 Windows 开始菜单中。iOS Safari打开 Safari。导航到 Wekan 登录页。点击底部中央的分享按钮方框带向上箭头的图标。向下滚动选择“添加到主屏幕Add to Home Screen”然后点击“添加Add”。Android Chrome打开 Chrome。导航到 Wekan 登录页。点击右上角菜单⋮选择“添加到主屏幕Add to home screen”。按屏幕提示完成安装。Android Firefox如该功能可用且未被移除打开 Firefox。导航到 Wekan 登录页。点击 URL 地址栏右侧带“”号的主屏图标按钮。按屏幕提示完成安装。Android Brave打开 Brave。导航到 Wekan 登录页。点击右下角菜单⋮选择“添加到主屏幕Add to home screen”。按屏幕提示完成安装。Android Opera打开 Opera。导航到 Wekan 登录页。点击右上角菜单⋮选择“添加到主屏幕Add to / Home screen”。按屏幕提示完成安装。Android Vivaldi打开 Vivaldi。导航到 Wekan 登录页。点击 URL 地址栏右侧的[V]按钮选择“添加到主屏幕Add to home screen”。按屏幕提示完成安装。源码侧Wekan 的 PWA 实现原理Manifest 路由与自定义注入Wekan 通过 server/routes/customHeadAssets.js 提供/site.webmanifest路由当管理后台开启customHeadEnabledcustomManifestEnabled且填写了customManifestContent时直接以application/manifestjson返回自定义清单否则回退到默认清单文件public/site.webmanifest.default同一路由文件还处理/.well-known/assetlinks.json支持customAssetLinksEnabled/customAssetLinksContent两个设置默认为 public/.well-known/assetlinks.json.default用于 Android 数字资产链接Digital Asset Links验证。页面头部注入由 server/lib/customHeadRender.js 完成无论是否启用自定义头都会输出基于productName的title与响应式viewportwidthdevice-width, initial-scale1, viewport-fitcover对应 issue #6419 的移动端布局修复仅在启用customManifestEnabled时注入link relmanifest href/site.webmanifest crossoriginuse-credentials。默认清单要点默认清单 public/site.webmanifest.default 的关键字段字段值说明name/short_nameWekan应用显示名称displaystandalone独立应用窗口无浏览器地址栏display_override[standalone]优先覆盖为独立窗口模式start_urlsign-in启动即进入登录页theme_color/background_color#000000主题与背景色orientationany支持横竖屏自适应iconsSVG PNG192/512 Windows 11 磁贴 Android iOS 全套覆盖桌面、主屏、磁贴与商店场景screenshotsscreenshot1.webp/screenshot2.webp1280x720供商店展示仓库 public 目录为这套清单准备了完整资源maskable_icon.png、monochrome-icon-512x512.png、windows11/下全套 Windows 磁贴与启动屏、android/android-launchericon-*.png、ios/下从 16 到 1024 的 Apple 图标以及favicon-16x16.png、favicon-32x32.png、favicon.ico等。Service Worker为“添加到主屏”准备的占位实现Wekan 的 Service Worker 位于 public/pwa-service-worker.js其源码注释明确说明它是“占位式 Service Worker”Dummy service worker仅注册install事件监听且不做任何缓存目的是满足移动浏览器“添加到主屏幕Add to home screen”所需的安装条件。客户端注册逻辑位于 client/00-startup.js检测navigator中存在serviceWorker后在页面load事件中用Meteor.absoluteUrl()拼接pwa-service-worker.js的绝对路径并register。注释特别指出使用Meteor.absoluteUrl是为了保证在 ROOT_URL 带子路径例如https://example.com/wekan的部署场景下路径依然正确。进阶以 Caddy PWABuilder 构建全屏 Android 应用以下内容来自原文档中 Wekan 维护者 xet7 制作官方 Android Play Store 应用的实际笔记。注意原文档明确提示该流程需要大量时间配置且主要面向维护者普通用户不推荐。发布到其他应用商店可参考 docs/Browsers/Browser-compatibility-matrix.md其中记录了 Microsoft Store 应用与 Android Play Store 应用均基于 PWABuilder 制作指向 demo/开发服务器https://boards.wekan.team。整体流程共 10 步使用 https://www.pwabuilder.com 创建 Android 应用。创建应用时选择 fullscreen全屏模式同时必须正确安装assetlinks.json见下文 Caddy 配置否则无法获得全屏效果。若没有签名密钥需自行生成若已有则可复用。Android 应用通过 Play Consolehttps://play.google.com/console/发布。PWABuilder 会提供 100 个可下载图标及 webmanifest 相关资源与仓库 public 目录中的资源对应。克隆 WeKan 仓库将第 2 步得到的 favicon 等资源加入wekan/public/并从源码构建 WeKan bundle构建方式可参考 docs/Features/Editor/Emoji.md。注意目前 WeKan 没有自定义 favicon 的功能若要支持 100 favicon 等自定义需要大量开发工作。在服务器上运行构建产物可参考 docs/Platforms/Propietary/OS/Windows/Offline.md 或 docs/Platforms/FOSS/HW/RaspberryPi/Raspberry-Pi.md。安装 Caddy配置参考 docs/Platforms/Webserver/Caddy.md为 PWA 站点示例https://boards.example.com配置assetlinks.json。其中填写的 SHA256 指纹来自你从 pwabuilder.com 下载的 Android.zip包关于 Play Console 中那 2 个 SHA256 密钥的来源可参见 pwabuilder 的 assetlinks issue#3867 评论区。仓库自带的默认文件 public/.well-known/assetlinks.json.default 中package_name为team.wekan.boards.twa内含两条sha256_cert_fingerprints可作为结构参考实际发布时需替换为你自己的包名与签名指纹。在 Play Console 侧边菜单中找到App Integrity按钮截图见下从中获取 Caddyfile 所需的 2 个 SHA256 密钥Caddy 使用 Tab 缩进。在/etc/caddy目录下可执行caddy format ca将格式化输出写入新文件验证成功后执行mv ca Caddyfile随后caddy validate校验、caddy reload重载配置。必要时用caddy upgrade升级升级后执行caddy stop与caddy start。相关场景可在加密 VM 上通过 Parallel Snaps 在一台服务器安装多个实例参见 wekan-snap 的 Many-Snaps-on-LXC 文档。最新要求中assetlinks.json应安装到PWA 的 URL如https://boards.example.com而早期是安装到主域名如https://example.com。为稳妥起见以下配置同时安装到两个位置写在/etc/caddy/Caddyfile中。更多细节见 PWABuilder 的 android 文档。关于 Caddy 2 配置中/.well-known文件位置可参考 Caddy 社区论坛的 “well-known file location” 讨论。参考/etc/caddy/Caddyfile完整配置# Redirecting http to https (redirect) { http { protocol http } redir http https://{host}{uri} } example.com { tls { alpn http/1.1 } header /.well-known/* Content-Type application/json header /.well-known/* Access-Control-Allow-Origin * respond /.well-known/assetlinks.json [ { relation: [delegate_permission/common.handle_all_urls], target: { namespace: android_app, package_name: team.example.boards.twa, sha256_cert_fingerprints: [ AA:AA... FIRST SHA256 KEY, 61:41... 2nd SHA256 KEY ] } } ] root * /data/websites/example.com file_server } boards.example.com { tls { alpn http/1.1 } header /.well-known/* Content-Type application/json header /.well-known/* Access-Control-Allow-Origin * respond /.well-known/assetlinks.json [ { relation: [delegate_permission/common.handle_all_urls], target: { namespace: android_app, package_name: team.example.boards.twa, sha256_cert_fingerprints: [ AA:AA... FIRST SHA256 KEY, 61:41... 2nd SHA256 KEY ] } } ] reverse_proxy 192.168.100.3:3025 }配置要点说明(redirect)片段将所有 HTTP 请求 301 重定向到 HTTPS主域名example.com与 PWA 域名boards.example.com都通过header /.well-known/*设置 JSON 响应头并开启 CORSrespond /.well-known/assetlinks.json直接内联返回 Android 数字资产链接 JSON其中relation固定为delegate_permission/common.handle_all_urlspackage_name与sha256_cert_fingerprints需替换为你的实际值alpn http/1.1限定 TLS 协商协议主域名块用rootfile_server托管静态站点PWA 域名块用reverse_proxy 192.168.100.3:3025将流量反代到内网 Wekan 服务。常见问题与注意事项全屏不生效多为assetlinks.json未正确安装到 PWA 域名的/.well-known/路径或sha256_cert_fingerprints与 Play Console App Integrity 中显示的密钥不一致导致。记得在 Caddyfile 中同时配置Content-Type: application/json与 CORS 响应头。Firefox 系浏览器桌面 Firefox 在兼容性矩阵中标注 PWA 为NoAndroid Firefox 安装入口存在但可能随版本被移除原文档对此做了明确提示。manifest 被自定义设置覆盖一旦在管理后台启用了customManifestEnabled/site.webmanifest将返回自定义内容而非 public/site.webmanifest.default自定义 link 标签中若再出现 manifest 链接会被 server/lib/customHeadRender.js 自动去重避免重复注入。子路径部署Service Worker 的注册路径经由Meteor.absoluteUrl()计算确保 Wekan 部署在子路径如/wekan时仍能正确加载pwa-service-worker.js。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考