GFast 安装说明

本文档介绍 GFast 项目的两种安装方式：Web 安装向导（推荐） 与 手工安装，以及前端项目的配置与启动。

一、环境要求

二、方式一：Web 安装向导（推荐）

安装器是一个独立于主程序的 Web 程序（install/install.go），通过浏览器分步完成全部配置。

1. 启动安装器

# 必须在项目根目录（gfast-v34/）下运行
# 先安装依赖
go mod tidy
# 运行安装程序
go run ./install

支持的可选参数：

go run ./install -addr 127.0.0.1:8890 -config manifest/config/config.yaml -no-open

启动后自动打开浏览器访问安装页面（如 http://127.0.0.1:8890）。

config.yaml 自动生成：manifest/config/config.yaml 被 git 忽略，从 git 拉取的项目只有模板 config.yaml.bak。安装器启动时检测到 config.yaml 不存在，会自动从模板复制创建，无需手工操作。

2. 六步配置说明

第 1 步：服务与网站（对应 server 节）

• 监听地址：主程序 HTTP 端口，如 :8808
• Swagger 文档：开启写入 /api.json 与 /swagger，生产建议关闭

第 2 步：数据库（对应 database.default 节）

• 类型：MySQL / PostgreSQL
• 填写主机、端口（自动带默认值 3306 / 5432）、账号、密码、库名、字符集
• 测试连接：验证账号密码与网络连通性
• 自动创建数据库：库不存在时执行 CREATE DATABASE（MySQL 检查 information_schema，PostgreSQL 连接 postgres 库检查 pg_database）
• 导入初始化 SQL（可选）：自动执行 resource/data/gfast-v34.sql（MySQL）或 resource/data/gfast-v34-pg.sql（PostgreSQL）建表脚本

第 3 步：缓存（同步写入 system.cache.model 与 gfToken.cacheModel）

• memory：内存缓存，单机开箱即用
• redis：填写地址/DB/密码，可测试连接（多实例部署推荐）
• dist：磁盘文件缓存，可自定义缓存目录

第 4 步：日志（对应 logger 节与 server.accessLogEnabled）

• 日志目录、文件名、级别、轮转周期、备份上限、终端输出
• HTTP 访问日志开关

第 5 步：前端（对应 gen.frontDir 与前端 .env 文件）

• 前端目录：默认 ../admin-ui（admin-ui 与后端项目平级），写入 config.yaml 的 gen.frontDir
• 开发端口：写入 admin-ui/.env 的 VITE_PORT（默认 5173，留空不修改）
• 后端接口地址：写入 .env.development 的 VITE_API_URL，作为 vite 开发代理 /api、/upload 的目标（默认按监听地址自动推导 http://127.0.0.1:8808）
• 生产接口地址：写入 .env.production 的 VITE_API_URL（同域部署保持 /，跨域填完整地址；留空且文件缺失时按 / 创建）
• 打包资源路径：写入 .env.production 的 VITE_PUBLIC_PATH（部署子路径填如 /sys/，根路径保持 /）
• 自动安装前端依赖：勾选后在安装最后一步执行 pnpm install（可切换 npm/cnpm/yarn）

第 6 步：完成安装

点击「开始安装」后，安装器先自动执行前置检查，全部通过才开始安装：

前置检查不产生任何副作用（不建库、不写文件）；即使绕过页面直接调用安装接口，服务端也会强制执行检查，不通过则拒绝安装。

3. 安装过程与备份机制

安装按顺序执行并逐项显示结果：

✓ 监听端口 / 数据库连接 / 缓存 / 前端环境   ← 前置检查
✓ 写入配置文件          ← 修改前自动备份
✓ 前端 .env 配置        ← 可选
✓ 导入初始化 SQL        ← 可选
✓ 安装前端依赖          ← 可选

• 写入前会把当前 config.yaml 备份为 config.yaml.bak-<时间戳>（如 config.yaml.bak-20260102150405）；若当前内容与模板 config.yaml.bak 完全一致（典型：首次安装由模板种子生成），则跳过生成时间戳文件，避免产生重复副本
• 回写基于 yaml.Node 解析，保留原注释、键序与引号风格；内容无变化时不写文件
• .env 文件修补同样只替换指定键的值，保留其余行；文件缺失时按模板创建
• 时间戳备份文件已被 git 忽略（.gitignore），不会污染版本库

4. 安装完成后

# 启动后端
go run main.go

# 启动前端（另开终端，在 admin-ui/ 目录）
pnpm dev

三、方式二：手工安装

不使用向导时按传统流程操作：

1. 创建数据库并导入建表脚本：

   # MySQL
   mysql -u用户名 -p -e "CREATE DATABASE gfast-v34 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
   mysql -u用户名 -p gfast-v34 < resource/data/gfast-v34.sql
   
   # PostgreSQL
   psql -U 用户名 -c "CREATE DATABASE \"gfast-v34\";"
   psql -U 用户名 -d gfast-v34 -f resource/data/gfast-v34-pg.sql

2. 复制配置模板并修改（该文件被 git 忽略，仓库中只有 .bak）：

   cp manifest/config/config.yaml.bak manifest/config/config.yaml

   至少修改 database.default.link 与 charset：

   database:
     default:
       # MySQL
       link: "mysql:用户名:密码@tcp(127.0.0.1:3306)/gfast-v34?charset=utf8mb4&parseTime=true&loc=Local"
       # PostgreSQL
       # link: "pgsql:用户名:密码@tcp(127.0.0.1:5432)/gfast-v34"
       charset: "utf8mb4"   # PostgreSQL 建议 UTF8

3. 按需修改缓存模式（system.cache.model 与 gfToken.cacheModel 两处需保持一致）、日志等配置。

4. 前端配置与启动见下一节。

四、前端配置与启动

前端项目位于 admin-ui/（与后端项目平级），基于 Vite，配置全部来自 .env 文件（可由安装向导自动生成）：

vite.config.ts 读取规则：

const port   = Number(env.VITE_PORT) || 5173
const backend = env.VITE_API_URL || 'http://127.0.0.1:8808'   // /api 与 /upload 代理目标
const base   = command === 'serve' ? './' : env.VITE_PUBLIC_PATH || '/'

说明：前端 axios 的 baseURL 为相对路径 /api/v1，开发环境经 vite 代理转发到后端，因此修改后端端口只需改 .env.development 的 VITE_API_URL，无需改前端代码。

常用命令（在 admin-ui/ 目录执行）：

pnpm install      # 安装依赖（首次必需）
pnpm dev          # 启动开发服务器（默认 http://localhost:5173）
pnpm build        # 生产构建（输出 dist/）

后台账号：

admin/123456

demo/Demo123

五、常见问题（FAQ）

Q1：启动安装器报「配置文件 manifest/config/config.yaml 不存在」？
确认在项目根目录运行；若模板也不存在，检查仓库是否完整（config.yaml.bak 必须存在）。正常情况下安装器会自动从 .bak 复制创建。

Q2：前置检查提示「监听端口不可用」？
主程序正在运行（端口被占用）——先停止 go run main.go，或向导里换一个监听端口。

Q3：提示「数据库 xxx 不存在，且未勾选自动创建数据库」？
回数据库步骤勾选「数据库不存在时自动创建」，或手工建库后重试。

Q4：提示「未在 PATH 中找到 pnpm」？
先安装：npm i -g pnpm；或在「前端」步骤改用 npm/cnpm/yarn，或取消勾选自动安装依赖后手工执行 pnpm install。

Q5：导入初始化 SQL 失败？
查看失败语句与错误信息（安装器会显示出错语句片段）。常见原因：库不为空（表已存在）、字符集问题。可清空数据库后重试，或按 FAQ 第 6 项手工导入。

Q6：如何手工导入初始化 SQL？
见「方式二：手工安装」第 1 步；脚本位于 resource/data/gfast-v34.sql（MySQL）与 gfast-v34-pg.sql（PostgreSQL）。

Q7：安装器支持达梦数据库吗？
不支持。安装器已移除达梦选项，仅适配 MySQL 与 PostgreSQL。

Q8：安装器修改配置会丢失注释吗？
不会。回写基于 yaml.Node（注释、键序、引号风格保留），且修改前自动生成带时间戳的备份文件。

Q9：如何更换安装器端口？
go run ./install -addr 127.0.0.1:9000（默认 8890，仅监听本机）。