AppKernia

从后台管理到跨平台 App，把时间留给你的业务。

AppKernia（AK）是一个面向生产项目的跨平台应用基座：Go API/Worker、React 管理后台，以及 uni-app x 移动端。后端以 OpenAPI 为 API 事实源，Admin 与 Mobile 共用权限、数据库和 zh-CN / en-US 国际化契约。

• 开源官网与文档：https://appkernia.com
• GitHub Pages 地址：https://payhon.github.io/AppKernia/
• 源码仓库：https://github.com/Payhon/AppKernia

如果 AppKernia 帮你少走了一些跨端与服务端集成的弯路，欢迎点一个 Star；如果它还缺少你需要的能力，也欢迎从文档、Issue、测试或代码开始贡献。

先看后台长什么样

应用版本、内容运营、文件素材、权限与接口文档，都可以从同一个工作区进入。下面是官网后台的真实界面导览：

7 张实拍截图轮播，每张停留 3 秒。下方提供静态大图，可点击放大查看。

查看模块截图 · 源码启动 · 单二进制安装 · 在线后台

想看具体操作？可继续查看 App 配置弹框、文章编辑器、文件选择组件 和 收纳式系统菜单。

你可以从这些能力开始

你的工作	AppKernia 提供的起点
搭建业务后台	React 管理界面、应用上下文、角色与权限、文件管理
运营 App 内容	文章、图文、视频、分类、专题与评论管理
管理移动版本	原生版本记录、平台筛选、发布状态与多语言更新说明
对接自己的客户端	OpenAPI 契约、生成 Client、按管理端与移动端划分的 API
开始本地体验	akone 单二进制内嵌后台，或从 Go / React 源码启动

后台模块一览

以下界面于 2026-10-22 使用 Chrome 从 AppKernia 官网后台 实际采集，关键标识、账号、存储配置及二维码已脱敏。线上版本与开源仓库可能存在版本或配置差异，具体能力以当前源码和文档为准；截图中的内容与数量仅代表采集时状态。

1. 工作区与数据概览

从一个入口查看应用与会员、资讯发布、通知和系统指标，按 7 / 30 / 90 天切换统计范围，再进入对应业务模块。

展开查看用户增长、内容发布、通知和登录趋势

2. App 升级中心

集中查看版本历史，按安装包类型、目标平台和发布状态筛选。原生升级支持 Android、iOS 与 HarmonyOS 的对应分发方式，更新说明支持中英文。

应用列表把编辑、升级中心、内容管理、客户端配置和发行页配置收进同一个操作菜单，按需要打开对应弹框。

应用编辑：基础信息、图标素材与双语启动设置

基础信息集中管理应用类型、默认语言、介绍与注册策略；图标和启动配置使用独立标签页。

客户端配置：分享场景、扫码白名单与登录方式

分享、扫码与登录分别配置。界面会说明哪些内容需要重新导出打包，哪些内容通过运行时配置刷新生效。

发行页配置与手机外观预览

维护下载入口和双语推广文案，并在后台查看手机尺寸的公开发行页预览。预览模拟外观，平台识别仍由当前浏览器决定。

3. 内容运营工作台

把文章、图文、视频与分类、专题、标签放在同一工作台，结合发布状态、首页属性与评论管理组织内容。

编辑时将 Meta 信息与正文分开管理。正文支持中英文标题、摘要、Markdown 工具栏、文件库插图，以及编辑与实时预览并排显示。

查看文章 Meta 信息和全屏正文编辑

4. 文件与素材管理

图片和视频素材以网格、表格或缩略图展示，可按文件状态、扫描状态、存储驱动与媒体类型筛选，查看详情或下载。

文件选择组件可以直接复用已有素材，也可以在弹框中上传新文件。 选择封面、站点 Logo 等文件时，使用同一套文件库界面：

• 按名称、上传时间范围和文件类型筛选，切换网格、表格或缩略图视图。
• 选择文件后在右侧预览，同时查看大小与扫描状态。
• 对话框支持拖动、调整大小、最大化及键盘操作；上传限制随当前存储配置展示。
• 仅允许选择状态可用且扫描安全的文件，确认前可以取消。

5. 权限目录

按模块、类型和状态检索稳定权限码，让后台页面与服务端授权使用同一套清晰的权限语言。目录只读，角色授权通过对应管理页面配置。

6. OpenAPI 接口文档

按公共能力、移动端和管理端浏览接口，查看参数、响应结构与请求示例。接入客户端时，可以直接围绕同一份契约协作。

7. 收纳式系统菜单与系统设置

日常业务导航保持清晰；系统能力集中收纳在左下角的齿轮入口。点击后弹出分组菜单，再展开对应子模块，不必一直占满侧栏。

系统配置进一步按用途分组，提供表单与表格两种模式。基本设置可集中维护站点名称、Logo、公开地址和维护状态。

播放系统设置、文件选择、App 配置和文章编辑细节导览

邮件设置：连接诊断与 SMTP 配置

诊断区域展示域名解析、连接、TLS、SMTP 握手与账号认证结果，发送服务在同一分组维护。

短信配置

登录注册

安全验证

提现配置

云存储与上传策略

地理位置服务

支付配置

微信配置

以上展示配置界面；关闭或未配置的可选能力不代表已接通第三方服务。

8. 系统设置的其他模块

平台身份、业务字典和地区目录各有独立管理入口，按模块组织信息。

分享配置：集中维护可复用的平台身份

第三方登录配置：平台身份与原生工程信息

字典管理：分类、双语标签与扩展策略

地区管理：按层级展开地区树

自媒体平台配置：平台账号与 App 使用范围

9. 组织、通知与运行管理

系统菜单还包含组织、权限、文件、通知、任务集成、审计安全、运行监控、AI 和移动端管理。以下展示各分组的代表界面；权限目录和文件库见前文。

组织管理：部门配置

通知中心：按渠道和语言维护模板

任务集成：Cron、时区与执行策略

审计安全：访问控制规则

运行监控：依赖、Worker 与队列摘要

AI 中心：模型接入入口

移动端管理：发布策略兼容入口

截图来源、尺寸与 GIF 说明见 素材索引。

技术栈

• Backend：Go 1.26、GoFrame、pgx/v5、sqlc、PostgreSQL 18、River。
• Admin：React、TypeScript、Vite、TanStack Router/Query、Ant Design。
• Mobile：uni-app x、UTS/UVue、VDOM、uView Ultra，并通过 AK UI 适配层使用组件。

环境要求

• Go 1.26.5（Makefile 会使用 GOTOOLCHAIN=go1.26.5）。
• Node.js 24.18.1、npm 11+；推荐通过 Corepack 使用 pnpm 11.18.0。
• Docker Desktop 或兼容的 Docker Engine + Compose v2，用于 PostgreSQL 和完整容器开发模式。
• Python 3，用于蓝图与国际化契约校验。

版本基线同时记录在 .nvmrc、.tool-versions 和根 package.json。可先检查本机环境：

make toolchain

HBuilderX、Xcode 和 DevEco Studio 只在开发对应移动平台时需要，doctor 会把它们标为可选工具。

快速开始：源码开发模式

这是日常修改 Backend 和 Admin 时推荐的方式：PostgreSQL 运行在 Docker 中，Go 与 Vite 直接运行在宿主机，便于断点调试和即时刷新。

git clone <your-fork-or-repository-url>
cd AppKernia
cp .env.example .env
make setup

make setup 会安装 pnpm 依赖、启动 PostgreSQL、执行当前数据库迁移链，并幂等写入核心权限和菜单。之后分别打开两个终端：

# 终端 1：同时启动 API 与 River Worker
make dev-backend

# 终端 2：启动 Vite Admin，自动代理 /admin-api 到 127.0.0.1:8080
pnpm dev

依赖安装完成后，也可以用 npm 调用同一套前端脚本：

npm run dev
npm test
npm run build

仓库以 pnpm-lock.yaml 作为锁文件事实源，因此依赖安装和 CI 使用 pnpm；npm run 路径用于调用标准 package scripts，避免产生第二份锁文件。

创建首个管理员时，密码仅从交互终端读取，不会进入命令历史或 .env：

make -C server bootstrap-admin

开发环境也可以让 seed core 幂等创建或补齐管理员授权。邮箱默认是 admin@appkernia.local，密码只能从 Git 和 Docker 构建上下文均忽略的文件读取：

mkdir -p .secrets
chmod 700 .secrets
printf 'Seed administrator password: '
read -r -s AK_LOCAL_SEED_PASSWORD; printf '\n'
printf '%s\n' "$AK_LOCAL_SEED_PASSWORD" > .secrets/seed-admin-password
unset AK_LOCAL_SEED_PASSWORD
chmod 600 .secrets/seed-admin-password
AK_SEED_ADMIN_PASSWORD_FILE="$PWD/.secrets/seed-admin-password" make -C server seed-core

出于开源安全考虑，数据库 Migration、源码和 Core Seed 不会内置固定密码；未设置 AK_SEED_ADMIN_PASSWORD_FILE 时 Core Seed 不创建账号，非开发环境则拒绝该选项。管理员密码至少 12 位；本机若由维护者准备了临时测试账号，其凭据只记录在 Git 忽略的位置，不得复制到提交、Issue、日志或截图。

默认访问地址：

• Admin：http://localhost:4173
• API readiness：http://localhost:8080/internal/v1/health/ready
• Admin public config：http://localhost:4173/admin-api/v1/auth/public-config

akone 单二进制安装

正式制品统一使用 akone。0.5.0 使用官方 R2 的 Shell 与五平台归档；npm 为独立 Preview 渠道，Homebrew 尚未发布：

# macOS / Linux
curl -fsSL https://static.appkernia.com/akone/latest.sh | sh

# 独立的历史 Preview 渠道（本次未更新）
npm install --global @appkernia/akone@preview

# macOS（尚未发布，本次不更新）
brew install payhon/tap/akone

仓库内可运行 make build-akone 构建带内嵌管理端的 server/bin/akone。akone serve 默认在二进制同目录创建 data/appkernia.db 并以 SQLite 启动；可用 --sqlite FILE、AK_SQLITE_PATH 或 YAML 覆盖。配置 AK_DATABASE_URL 时继续使用完整 PostgreSQL 模式。

安装器会在下载后校验版本目录中的 SHA-256，默认写入用户目录且不会调用 sudo、修改 shell 配置或自动注册系统服务。运行、YAML、环境变量和 Agent CLI 见 akone 使用手册，制品、预览版和维护者流程见 akone 发行手册。

快速开始：全 Docker 模式

如果只想运行完整系统而不在宿主机安装 Go/Node 依赖：

cp .env.example .env
make docker-up
make docker-bootstrap-admin

打开 http://localhost:4174。查看日志或停止服务：

make docker-logs
make docker-down

AK_ADMIN_PORT、AK_ADMIN_ORIGIN 和 AK_BOOTSTRAP_* 可以在 .env 中覆盖。修改 Admin 端口时需同步修改 AK_ADMIN_ORIGIN。不要将管理员密码、生产密钥或第三方凭据写入 .env 或提交到 Git。

开发、测试与构建命令

前端脚本均可使用 pnpm <script> 或 npm run <script>：

命令	作用
pnpm dev	启动 Admin Vite 开发服务器
pnpm dev:docs	启动 Rspress 文档站
pnpm test	运行 Admin Vitest 测试
pnpm test:e2e:admin	运行 Admin 双语关键 E2E/视觉测试
pnpm build	构建 Admin 与文档站生产静态资源
pnpm check:docs	校验并构建双语文档、死链、锚点、OpenAPI 镜像与 Sitemap
pnpm check	生成契约代码并执行 lint、类型、测试、构建和蓝图校验

后端命令集中在 server/Makefile：

命令	作用
make -C server dev	从源码同时运行 API 与 Worker
make -C server dev-api	仅运行 API
make -C server dev-worker	仅运行 Worker
make -C server test	运行全部 Go 测试
make -C server test-race	使用 race detector 运行测试
make -C server build	构建 server/bin/ak-api、ak-worker、ak-cli
make -C server db-setup	执行迁移和幂等 Seed
make -C server doctor	检查当前 SQLite/PostgreSQL 连通性
make -C server check	检查格式、go vet 和测试

根目录还有跨项目入口：

make build       # Backend + Admin + Docs
make test        # Backend + Admin
make check       # 蓝图 + Backend + Admin + Mobile + Docs 静态门禁

需要数据库集成测试时，显式提供隔离的测试数据库，禁止指向生产库：

AK_TEST_DATABASE_URL='postgres://appkernia:appkernia-dev-only@localhost:55432/appkernia_test?sslmode=disable' \
  make -C server test-integration

代码生成与契约

OpenAPI、权限、迁移与国际化契约必须同步修改。生成文件禁止手改：

make -C server sqlc-generate
pnpm generate:admin
python3 blueprint/scripts/validate_i18n_contract.py

Admin 只调用 /admin-api/v1，Mobile 只调用 /api/v1。所有 API 请求遵守 Accept-Language / Content-Language 契约，稳定错误码不随语言变化。

仓库结构

apps/ak-admin       React 管理后台
apps/ak-docs        Rspress 开源官网与中英文文档站
apps/ak-mobile      uni-app x 移动端
server              Go API、Worker、CLI
blueprint           架构蓝图、机器可读契约与校验器
design-system       Admin/Mobile 设计系统与 UI 产物
docs                ADR、实施状态与交付报告

参与开发前请阅读根目录及所属子项目的 AGENTS.md。贡献流程见 CONTRIBUTING.md，社区行为约定见 CODE_OF_CONDUCT.md，漏洞报告方式见 SECURITY.md。

License

AppKernia 使用 MIT License。