HaiO安装与快速开始

安装与快速开始

本章将带你在 5～10 分钟内完成 Haio（海鸥）系统的安装、初始化、后台登录，并快速理解整体结构与开发入口。

1. 环境要求

1.1 服务器环境（推荐）

Linux（CentOS / Ubuntu / Debian 均可）
Nginx 或 Apache
PHP 8.1+（推荐 8.2）
MySQL 5.7+ / MariaDB 10.3+
Composer 2.x
Node.js 18+（用于前后端 Vue 构建）

1.2 PHP 必须启用的扩展

建议开启：

pdo_mysql
mbstring
openssl
json
curl
fileinfo
tokenizer
zip
gd（用于图片类插件）

2. 获取源码与目录结构

你拿到的 Haio 完整包一般包含：

主程序（PHP 后端）
插件（plugins/*）
前台 Vue（portal-vue 或 portal）
后台 Vue（vue-admin）
SQL（全库 / patch / seed）

目录示例：

复制代码

haio/
 ├─ app/                  # 应用层控制器/业务
 ├─ bootstrap/            # 启动引导
 ├─ config/               # 配置目录（推荐）
 ├─ database/             # 主库 schema.sql
 ├─ install/              # 安装向导视图
 ├─ plugins/              # 插件目录（核心）
 ├─ public/               # Web 根目录
 ├─ routes/               # 主程序路由
 ├─ src/                  # 框架核心
 ├─ storage/              # 日志/缓存/上传
 ├─ vendor/               # composer 依赖
 └─ .env                  # 环境配置

3. 部署方式（推荐：Nginx + public 目录）

3.1 Nginx 站点根目录

请务必指向：

复制代码

/www/wwwroot/haio/public

不要直接指向项目根目录，否则会导致：

路径解析错误
安装向导资源找不到
静态资源失效
路由异常

3.2 Nginx Rewrite（示例）

复制代码

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

4. 权限与日志（企业级必做）

Haio 运行时必须可写目录：

复制代码

storage/
storage/logs/
storage/uploads/
public/uploads/

5. 安装系统（Install 向导）

5.1 访问安装页面

浏览器打开：

复制代码

http://你的域名/install

你将进入 Haio 安装向导：

Step1：环境检测
Step2：数据库配置
Step3：初始化数据
Step4：完成安装

5.2 已安装提示（重要）

如果系统已安装过，再访问 /install 将提示：

已安装完成
请前往后台登录
或提供重新安装说明（需手动删除 lock）

安装锁文件通常位于：

复制代码

storage/installed.lock

6. 初始化数据库

Haio 的数据库导入有两种方式：

6.1 方式 A：安装向导自动初始化（推荐）

安装向导会执行：

database/schema.sql
plugins/*/database/schema.sql
并写入默认管理员

6.2 方式 B：手动导入 SQL（高级）

适用于：

生产环境迁移
备份恢复
数据库分离部署

手动导入示例：

bash 复制代码

mysql -uroot -p haio < database/schema.sql
mysql -uroot -p haio < plugins/portal/database/schema.sql
mysql -uroot -p haio < plugins/marketplace/database/schema.sql
...

7. 默认后台账号

系统初始化后默认会创建：

用户名：admin
密码：123456

建议首次登录后立即修改密码。

8. 后台访问（Vue Admin）

后台入口：

复制代码

http://你的域名/haioAdmin

登录页：

复制代码

http://你的域名/haioAdmin/login

9. 前台门户访问（Portal）

门户首页：

复制代码

http://你的域名/

文档中心：

复制代码

http://你的域名/docs

资讯：

复制代码

http://你的域名/news

版本与下载：

复制代码

http://你的域名/download

生态与伙伴：

复制代码

http://你的域名/ecosystem
http://你的域名/partners

10. 快速验证接口（Health Check）

Haio 推荐提供健康检查接口：

复制代码

/healthz
//healthz
///healthz

正常返回示例：

json 复制代码

{"code":0,"message":"ok","time":"2026-02-xx xx:xx:xx"}

11. 第一次开发：创建一个插件

Haio 推荐所有业务都以插件形式开发。

插件目录：

复制代码

plugins/your_plugin/

插件通常包含：

复制代码

plugins/demo/
 ├─ routes/
 │   ├─ web.php
 │   └─ api.php
 ├─ src/
 │   ├─ Controllers/
 │   ├─ Models/
 │   └─ Services/
 ├─ database/
 │   ├─ schema.sql
 │   └─ patch.sql
 └─ plugin.json

12. 开发模式（前后端分离）

12.1 后端开发

后端只负责：

API
权限校验
数据库读写
插件生命周期

12.2 前端开发（Vue）

portal-vue：前台门户
vue-admin：后台管理

开发启动：

bash 复制代码

npm i
npm run dev

生产构建：

bash 复制代码

npm run build

13. 常见问题（安装阶段）

13.1 访问直接 500

一般原因：

storage/logs 不可写
vendor 未安装
PHP 扩展缺失

13.2 "无法解析服务: response / router"

一般原因：

服务未绑定
bootstrap 初始化顺序错误
路由加载时 router 尚未注册

13.3 安装页面静态资源 404

原因：

Nginx root 没指向 public
rewrite 规则错误
install assets 未发布到 public