#从零运行 AppKernia

这条路径只要求你安装 Git 和 Docker Desktop。Go、Node 与 PostgreSQL 都由容器提供，适合第一次体验。

#1. 安装基础工具

• Git
• Docker Desktop 或带 Compose v2 的 Docker Engine

确认 Docker 已启动：

git --version
docker version
docker compose version

三条命令都应正常返回版本号。

#2. 拉取源码

git clone https://github.com/Payhon/AppKernia.git
cd AppKernia

如果你准备贡献代码，推荐先在 GitHub Fork，再克隆自己的 Fork。

#3. 创建本地配置

cp .env.example .env

仓库提供的值只用于本机开发。不要把 .env、管理员密码、Token、私钥或第三方凭据提交到 Git。

#4. 启动数据库、迁移、API 与 Admin

make docker-up

第一次运行需要构建镜像，耗时取决于网络和机器性能。命令会按顺序：

1. 启动 PostgreSQL 18。
2. 执行数据库迁移。
3. 幂等写入核心权限、菜单和配置种子。
4. 启动 Go API 与 React Admin 静态站。

#5. 创建第一个管理员

make docker-bootstrap-admin

按照终端提示输入至少 12 位的密码。密码只从交互终端读取，不会写入 Git 或命令历史。默认开发邮箱来自 .env 中的 AK_BOOTSTRAP_EMAIL，你可以在执行前改成自己的本地测试邮箱。

Core Seed 不内置管理员固定密码。重复执行 make docker-bootstrap-admin 会补齐已有管理员的角色、权限和菜单，但不会覆盖已有密码，因此不能把它当作密码重置命令。Docker 构建上下文也会排除 .secrets/；需要使用密码文件完成可重复的本地初始化时，请按源码开发模式中的开发专用方法操作。

#6. 打开系统

• Admin：http://localhost:4174
• API readiness：http://localhost:8080/internal/v1/health/ready（源码模式可直接访问；Docker Admin 通过内部 API 容器通信）

如果 Docker 模式没有把 API 端口发布到宿主机，使用下面的命令检查容器健康：

docker compose ps
docker compose logs api --tail=100

看到 postgres、api、admin 为 healthy，且浏览器能打开登录页，就完成了第一次启动。

#7. 停止系统

make docker-down

数据库数据保存在 Docker volume 中，普通 docker compose down 不会删除它。需要重建空数据库时请先备份；不要在不理解影响的情况下删除 volume。

#下一步

• 需要热更新和断点调试：进入源码开发模式。
• 需要运行移动端：进入移动端开发。
• 遇到问题：查看故障排查。