02 快速开始

环境要求

• PHP >= 8.1（扩展：pdo_mysql、curl、json、mbstring、openssl、zip）
• MySQL 5.7+ 或 MariaDB 10.3+
• Node.js 18+（仅开发/构建前端时需要）
• Composer 2.x

---

一键启动（推荐）

cd kede-finance
bash scripts/dev-all.sh

脚本会：

1. 启动 PHP 内置服务器（:8800，带 public/router.php）
2. 启动前台 Vite（:5273）
3. 启动后台 Vite（:5173）

访问地址

地址	说明
http://localhost:5273	前台 SPA
http://127.0.0.1:5173/admin/login	后台开发 SPA
http://127.0.0.1:8800/admin/	后台生产构建（若已 npm run build）
http://127.0.0.1:8800/ping	API 探活

---

首次安装

若未安装（无 public/install.lock）：

1. 访问 http://127.0.0.1:8800/setup
2. 按向导配置数据库、管理员账号
3. 完成后生成 install.lock

---

手动分步启动

# 终端 1：PHP
cd kede-finance
php -S 127.0.0.1:8800 -t public public/router.php

# 终端 2：前台
cd kede-finance/frontend/home
npm install
npm run dev

# 终端 3：后台
cd kede-finance/frontend/admin
npm install
npm run dev

---

环境变量（.env）

复制 .example.env 为 .env，常用项：

APP_DEBUG = true

[DATABASE]
HOSTNAME = 127.0.0.1
DATABASE = kede_finance
USERNAME = root
PASSWORD =
PREFIX   = kd_

[APP]
UPGRADE_SERVER = https://update.kede-finance.com
MARKETPLACE_SERVER = https://market.kede-finance.com

• UPGRADE_SERVER：系统热更新服务器
• MARKETPLACE_SERVER：插件市场远程地址（仅开发环境；生产留空，插件用压缩包安装）

---

构建生产前端

cd kede-finance/frontend/home && npm run build
cd kede-finance/frontend/admin && npm run build

产物分别输出到 public/index.html 与 public/admin/。

---

常见问题

Q: 后台 401 / 静态资源 404？
开发模式请用 :5173/admin/login，API 代理到 :8800。不要用 :8800/admin/login 访问未构建的 Vite 资源。

Q: /admin/* 接口全部 404 / 提示「控制器不存在 app\controller\Auth」？
多半是用 php think run 启动的。请改用 php -S 127.0.0.1:8800 public/router.php（或 scripts/dev-all.sh）。think run 不加载 public/router.php，会与 public/admin/ 静态目录冲突，导致多应用路由解析失败。

Q: 插件市场无法安装 / 提示找不到安装包？
生产/内网不支持市场离线部署。请将插件 zip 解压到 public/plugins/{type}/{name}/，在 本地插件 Tab 安装。开发环境需配置 MARKETPLACE_SERVER 且服务器能访问外网。

Q: 插件市场列表为空？
确认存在 resources/marketplace/catalog.json；开发环境可运行 php scripts/build-marketplace.php 重新生成目录。

Q: 如何重置安装？
删除 public/install.lock 并清空数据库（慎用）。

---

下一章：03-目录结构