签入版本

EasyGoAdmin_Gin_AntdVue/zh/quickstart/backend-start.md

@@ -1,196 +1,79 @@
-# 2.2 后端服务启动
+# 2.4 后端服务启动
 
-:::warning 特别提醒
-官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。
+:::tip 概述
+后端是单二进制服务，入口 `cmd/api`。启动时完成配置校验、数据库/缓存初始化、路由注册与定时任务装配，监听 `:8000`。
 :::
 
-## 步骤一：获取源码
+## 启动命令
 
-前往 [官方网站](https://www.rxthink.cn) 购买授权后，按以下步骤获取源码：
+```bash
+# 前台启动（读 config/config.yaml）
+make run
+
+# Windows 无 make 时
+make.bat run
+```
+
+## 启动过程
 
 ```text
-1. 登录[官方网站](https://www.rxthink.cn)，进入「个人中心」→「我的订单」页面。
-2. 在订单列表中找到已购买的授权订单，点击「下载」按钮。
-3. 下载的压缩包包含完整的前后端源码、数据库脚本及部署配置文件。
-4. 将压缩包解压到本地开发目录（如 D:\xampp8.2\htdocs\ 或 ~/www/）。
+读取配置并校验（fail-fast：JWT 密钥与 DSN 不合法直接退出）
+        │
+        ▼
+初始化日志 / 缓存（Redis 探测失败自动降级内存并告警）
+        │
+        ▼
+连接数据库（gorm.Open + 连接池参数）
+        │
+        ▼
+注册路由（registerControllers 内 Bind 反射扫描全部控制器，
+         写入路由元数据表；公开白名单/权限码/日志配置同源落表）
+        │
+        ▼
+启动定时任务调度器（service.DaemonInit）
+        │
+        ▼
+监听 server.address（默认 :8000）
 ```
 
+## 常用启动变体
+
 ```bash
-# 进入项目目录（以实际解压路径为准）
-cd RXThinkCMF_ThinkPhp8_EleVue
+make build                 # 编译到 bin/
+./bin/admin-server         # 直接运行编译产物（Windows: bin\ 下可执行文件）
+
+# 环境变量覆盖配置示例（临时切库）
+APP_DATABASE_DEFAULT_DBNAME=mydb APP_SERVER_ADDRESS=:9000 make run
 ```
 
-:::tip 温馨提示
-1. 源码包请务必从[官方网站](https://www.rxthink.cn)订单中心下载，确保获取的是正版授权的最新版本。
-2. 授权有效期内可无限次下载最新版本，版本更新后可重新下载获取最新源码。
-3. 解压后请先阅读根目录下的 `README.md` 和 `CHANGELOG.md` 了解版本更新内容。
-:::
-
-## 步骤二：安装 Composer 依赖
+## 验证服务
 
 ```bash
-# -----------------------------------------------------------------------------
-# 安装项目依赖（从 composer.lock 精确安装，确保版本一致）
-# -----------------------------------------------------------------------------
-# install → 读取 composer.lock，安装锁定版本的依赖
-# 安装完成后生成 vendor/ 目录，包含所有第三方库
-composer install
-
-# -----------------------------------------------------------------------------
-# 如果国内下载慢，先配置阿里云镜像（加速依赖下载）
-# -----------------------------------------------------------------------------
-# config -g → 修改全局配置（所有项目生效）
-# repo.packagist → 设置 Packagist 仓库的镜像地址
-composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
-composer install
+curl http://127.0.0.1:8000/api/health
 ```
 
-安装完成后，项目根目录会生成 `vendor/` 目录，包含所有第三方依赖。
+健康检查 `/api/health` 为免登录端点，返回 200 即服务就绪。
 
-## 步骤三：配置环境文件
+## 日志
 
-```bash
-# 复制环境配置模板（.env.example 是模板文件，.env 是实际配置）
-cp .env.example .env
-```
+- 控制台输出由 `logger.stdout` 控制
+- 文件日志写入 `log/` 目录（`logger.path`）
+- 启动日志只打阶段就绪与非常态告警，不复述配置明细
 
-编辑 `.env` 文件，配置数据库连接等信息：
+## 优雅关闭
 
-```ini
-; 开启调试模式（开发环境 true，生产环境必须 false）
-APP_DEBUG = true
+进程收到退出信号后按序关闭：**停 HTTP → 停定时任务 → 关 DB → 关 Redis**。直接 Ctrl+C 即触发完整关闭链。
 
-; 数据库连接配置
-[DATABASE]
-TYPE = mysql                        ; 数据库类型（mysql / pgsql / sqlsrv / oracle / sqlite）
-HOSTNAME = 127.0.0.1                ; 数据库服务器地址
-DATABASE = rxthinkcmf.thinkphp8.elevue  ; 数据库名称
-USERNAME = root                     ; 数据库用户名
-PASSWORD = root                     ; 数据库密码
-HOSTPORT = 3306                     ; 数据库端口
-PREFIX = think_                     ; 表前缀
+## 常见启动失败
 
-; JWT 签名密钥（生产环境务必修改为强随机字符串）
-[JWT]
-SECRET = rxthinkcmf_jwt_secret_key_2024
+| 现象 | 原因与处理 |
+|---|---|
+| 配置校验失败退出 | JWT 密钥为空/过短，或 DSN 字段不完整——修正 config.yaml 或环境变量 |
+| 数据库连接失败 | MySQL 未启动或账号密码错误——核对 database 节 |
+| 端口占用 | `server.address` 改端口或释放 8000 端口 |
 
-; 文件上传配置
-[FILE]
-UPLOAD_DIR = D:\xampp8.2\htdocs\RXThinkCMF_ThinkPhp8_EleVue\uploads  ; 上传文件存储目录（绝对路径）
-DOMAIN_URL = http://file.thinkphp8.elevue  ; 文件访问域名
-```
+更多见 [2.8 常见问题 FAQ](/zh/quickstart/faq.html)。
 
-:::danger 生产环境务必修改
-1. `[JWT]` 下的 `SECRET` 必须修改为强随机字符串，生成方式：`php -r "echo bin2hex(random_bytes(32));"`
-2. `APP_DEBUG` 生产环境必须设为 `false`
-3. `[DATABASE]` 下的 `PASSWORD` 必须修改为强密码
-:::
+## 下一步
 
-## 步骤四：启动内置开发服务器
-
-ThinkPHP 内置了 PHP 开发服务器，无需安装 Nginx/Apache 即可启动：
-
-```bash
-# -----------------------------------------------------------------------------
-# 启动开发服务器（默认监听 127.0.0.1:8000）
-# -----------------------------------------------------------------------------
-# run → 启动 ThinkPHP 内置的 PHP 开发服务器
-# 启动后浏览器访问 http://localhost:8000 即可
-php think run
-
-# -----------------------------------------------------------------------------
-# 指定端口（当 8000 被占用时更换端口）
-# -----------------------------------------------------------------------------
-# --port → 指定监听端口
-php think run --port 8080
-
-# -----------------------------------------------------------------------------
-# 指定主机和端口（允许局域网其他设备访问）
-# -----------------------------------------------------------------------------
-# --host 0.0.0.0 → 监听所有网络接口（默认只监听 127.0.0.1）
-# 适用于手机调试、前后端分离开发等场景
-php think run --host 0.0.0.0 --port 8000
-```
-
-启动成功后会看到：
-
-```html
-ThinkPHP Development server is started
-<http://0.0.0.0:8000>
-You can exit with `CTRL-C`
-```
-
-## 步骤五：验证服务
-
-```bash
-# -----------------------------------------------------------------------------
-# 访问根路径，确认服务正常运行
-# -----------------------------------------------------------------------------
-# curl → 命令行 HTTP 客户端工具
-# 正常响应：{"code":200,"msg":"RxThinkCMF API Server","data":{"version":"1.0.0"}}
-curl http://localhost:8000/
-
-# -----------------------------------------------------------------------------
-# 测试登录接口（POST 请求 + JSON 请求体）
-# -----------------------------------------------------------------------------
-# -X POST       → 使用 POST 方法
-# -H            → 设置请求头（Content-Type: application/json）
-# -d            → 发送 JSON 格式的请求体
-curl -X POST http://localhost:8000/api/login \
-  -H "Content-Type: application/json" \
-  -d '{"username":"admin","password":"123456"}'
-
-# 测试租户账号登录
-curl -X POST http://localhost:8000/api/login \
-  -H "Content-Type: application/json" \
-  -d '{"username":"tenant001","password":"123456"}'
-```
-
-:::tip 内置演示账号
-| 账号 | 密码 | 角色 | 说明 |
-|------|------|------|------|
-| admin | 123456 | 超级管理员 | 平台管理，可管理所有租户 |
-| tenant001 | 123456 | 租户管理员（客户租户A） | 租户视角，体验数据隔离效果 |
-:::
-
-## 常见问题
-
-### 1. `composer install` 报错内存不足
-
-```bash
-# -d memory_limit=-1 → 取消 PHP 内存限制（-1 表示无限制）
-php -d memory_limit=-1 /usr/local/bin/composer install
-```
-
-### 2. `vendor/` 目录权限问题
-
-```bash
-# 755 → owner 可读写执行，group/others 可读可执行
-chmod -R 755 vendor/
-```
-
-### 3. 数据库连接失败
-
-检查 `.env` 中的数据库配置是否正确：
-
-```bash
-# 1. 检查 .env 中 [DATABASE] 配置：HOSTNAME、PORT、USERNAME、PASSWORD、DATABASE 是否正确
-# 2. 确认数据库服务已启动
-# 3. 用原生 SQL 测试连接是否正常（以 MySQL 为例）
-mysql -h 127.0.0.1 -P 3306 -u root -p -e "SELECT 1;"
-```
-
-### 4. 端口被占用
-
-```bash
-# Windows：查找占用 8000 端口的进程
-# findstr → Windows 版的 grep（过滤文本）
-netstat -ano | findstr :8000
-
-# macOS / Linux：查找占用 8000 端口的进程
-# -i :8000 → 只显示使用 8000 端口的进程
-lsof -i :8000
-
-# 更换端口启动（避免冲突）
-php think run --port 8080
-```
+→ [2.5 前端服务启动](/zh/quickstart/frontend-start.html)

EasyGoAdmin_Gin_AntdVue/zh/quickstart/database-init.md

@@ -1,372 +1,65 @@
-# 2.4 数据库初始化
+# 2.2 数据库初始化
 
 :::tip 概述
-本章指导您完成数据库的创建和 SQL 脚本导入。项目为每种数据库提供了独立的 SQL 脚本，存放在 `document/` 目录下按数据库类型分组。
+项目在 `document/` 目录提供各数据库方言的初始化脚本。导入种子数据后即可用内置账号登录后台。
 :::
 
-## SQL 脚本目录结构
+## MySQL 初始化（默认）
 
-```text
-document/
-├── mysql/
-│   └── rxthinkcmf.thinkphp8.elevue.sql      # MySQL 版本
-├── postgresql/
-│   └── rxthinkcmf.thinkphp8.elevue.sql      # PostgreSQL 版本
-├── sqlserver/
-│   └── rxthinkcmf.thinkphp8.elevue.sql      # SQL Server 版本
-├── oracle/
-│   └── rxthinkcmf.thinkphp8.elevue.sql      # Oracle 版本
-└── sqlite/
-    └── rxthinkcmf.thinkphp8.elevue.sql      # SQLite 版本
-```
-
-各数据库脚本已针对对应的 SQL 语法做了适配，可直接导入使用，无需手动转换。
-
----
-
-## MySQL 初始化
-
-### 1. 创建数据库
+项目 `document/mysql/` 提供完整种子脚本：
 
 ```bash
-# 连接 MySQL（-u root 以 root 用户，-p 交互式输入密码）
-mysql -u root -p
+# 创建库（库名与 config.yaml 的 database.default.dbname 一致）
+mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS \`easygoadmin.gin.elevue\` DEFAULT CHARSET utf8mb4;"
+
+# 导入种子数据
+mysql -uroot -p easygoadmin.gin.elevue < document/mysql/easygoadmin.gin.elevue.sql
 ```
 
+## 其他方言
+
+| 方言 | 脚本目录 |
+|---|---|
+| PostgreSQL | `document/postgresql/` |
+| SQL Server | `document/sqlserver/` |
+| SQLite | `document/sqlite/` |
+| Oracle | `document/oracle/` |
+
+方言切换只需改 `config.yaml` 的 `database.default.driver` 与连接字段，代码零改动。
+
+## 导入了什么
+
+种子脚本创建 25 张 `gin_` 前缀表，覆盖：
+
+| 域 | 表 |
+|---|---|
+| 组织权限 | gin_user、gin_role、gin_menu、gin_dept、gin_level、gin_position、gin_user_role、gin_role_menu、gin_tenant |
+| 内容管理 | gin_article、gin_category、gin_notice、gin_link |
+| 数据配置 | gin_dict、gin_dict_item、gin_param、gin_config、gin_config_item、gin_city |
+| 任务日志 | gin_job、gin_job_log、gin_operation_log、gin_login_log |
+| 工具 | gin_file_template、gin_example（示例模块，第 3 章贯穿案例） |
+
+完整表结构见 [附录 B 数据库表结构速查](/zh/appendix/database-tables.html)。
+
+## 公共字段约定
+
+所有表遵循统一审计字段（由全局 Create 钩子在写入时补齐）：
+
+| 字段 | 说明 |
+|---|---|
+| id | 主键 |
+| create_user / create_time | 创建人 / 创建时间 |
+| update_user / update_time | 更新人 / 更新时间 |
+| del_flag | 软删标记（0 正常 / 1 删除） |
+| tenant_id | 租户 ID（租户隔离依据） |
+
+## 验证导入
+
 ```sql
--- 创建项目数据库
--- CHARACTER SET utf8mb4 → 支持 emoji 等四字节字符
--- COLLATE utf8mb4_general_ci → 不区分大小写的排序规则
-CREATE DATABASE `rxthinkcmf.thinkphp8.elevue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
-EXIT;
+SELECT COUNT(*) FROM gin_user;    -- 应有内置账号
+SELECT COUNT(*) FROM gin_menu;    -- 应有完整菜单树
 ```
 
-### 2. 导入 SQL 脚本
+## 下一步
 
-```bash
-# -----------------------------------------------------------------------------
-# 导入 MySQL 专用初始化脚本
-# -----------------------------------------------------------------------------
-# -u root -proot → 数据库用户名和密码
-# rxthinkcmf...    → 目标数据库名
-# < file.sql       → 将 SQL 文件内容作为 mysql 命令的输入
-mysql -u root -proot rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-:::tip 温馨提示
-导入完成后，数据库中包含完整的表结构和初始数据（管理员账号、菜单、字典、城市数据等），可直接使用。
-:::
-
-### 3. 配置 .env
-
-```ini
-[DATABASE]
-TYPE = mysql                        ; 数据库类型
-HOSTNAME = 127.0.0.1                ; 数据库地址
-DATABASE = rxthinkcmf.thinkphp8.elevue  ; 数据库名
-USERNAME = root                     ; 用户名
-PASSWORD = root                     ; 密码
-HOSTPORT = 3306                     ; 端口
-PREFIX = think_                     ; 表前缀
-```
-
----
-
-## PostgreSQL 初始化
-
-### 1. 创建数据库
-
-```bash
-# 以 postgres 系统用户身份进入 PostgreSQL 命令行
-sudo -u postgres psql
-```
-
-```sql
--- 创建数据库用户（如已存在可跳过）
-CREATE USER postgres WITH PASSWORD 'root';
-
--- 创建项目数据库
--- OWNER postgres → 指定数据库所有者
--- ENCODING 'UTF8' → 使用 UTF-8 编码
-CREATE DATABASE "rxthinkcmf.thinkphp8.elevue" OWNER postgres ENCODING 'UTF8';
-
--- 授予用户对该数据库的所有权限
-GRANT ALL PRIVILEGES ON DATABASE "rxthinkcmf.thinkphp8.elevue" TO postgres;
-\q
-```
-
-### 2. 导入 SQL 脚本
-
-```bash
-# -----------------------------------------------------------------------------
-# 导入 PostgreSQL 专用初始化脚本
-# -----------------------------------------------------------------------------
-# -U postgres → 连接用户
-# -d ...     → 目标数据库
-# -f file.sql → 执行 SQL 文件
-psql -U postgres -d rxthinkcmf.thinkphp8.elevue -f document/postgresql/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### 3. 配置 .env
-
-```ini
-[DATABASE]
-TYPE = pgsql                       ; 数据库类型改为 pgsql
-HOSTNAME = 127.0.0.1
-DATABASE = rxthinkcmf.thinkphp8.elevue
-USERNAME = postgres                ; PostgreSQL 默认用户
-PASSWORD = root
-HOSTPORT = 5432                    ; PostgreSQL 默认端口
-PREFIX = think_
-```
-
----
-
-## SQLite 初始化
-
-### 1. 创建数据库文件
-
-```bash
-# 安装 PHP 的 SQLite 扩展（如尚未安装）
-sudo apt install php8.2-sqlite3
-
-# 创建数据库文件存放目录（-p 参数：目录不存在时自动创建）
-mkdir -p /www/api/runtime
-
-# 创建空的 SQLite 数据库文件（touch 创建空文件）
-touch /www/api/runtime/database.sqlite
-```
-
-### 2. 导入 SQL 脚本
-
-```bash
-# -----------------------------------------------------------------------------
-# 导入 SQLite 专用初始化脚本
-# -----------------------------------------------------------------------------
-# sqlite3 → SQLite 命令行工具
-# 数据库文件路径 → SQLite 数据库存储在单个文件中
-# < file.sql → 将 SQL 文件作为输入执行
-sqlite3 /www/api/runtime/database.sqlite < document/sqlite/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### 3. 配置 .env
-
-```ini
-[DATABASE]
-TYPE = sqlite                      ; 数据库类型改为 sqlite
-DATABASE = /www/api/runtime/database.sqlite  ; SQLite 文件路径
-PREFIX = think_
-```
-
-:::tip SQLite 特点
-- 无需安装数据库服务器，数据存储在单个文件中
-- 适合开发环境、小型项目或嵌入式场景
-- 文件路径需确保 PHP 进程有读写权限
-:::
-
----
-
-## SQL Server 初始化
-
-### 1. 创建数据库
-
-```bash
-# -----------------------------------------------------------------------------
-# 使用 sqlcmd 创建数据库
-# -----------------------------------------------------------------------------
-# -S localhost → 服务器地址
-# -U sa       → 用户名（sa 为 SQL Server 管理员）
-# -P root     → 密码
-# -Q          → 执行 SQL 查询后退出
-# COLLATE Chinese_PRC_CI_AS → 中文排序规则（不区分大小写）
-sqlcmd -S localhost -U sa -P root -Q "CREATE DATABASE [rxthinkcmf.thinkphp8.elevue] COLLATE Chinese_PRC_CI_AS"
-```
-
-### 2. 导入 SQL 脚本
-
-```bash
-# -----------------------------------------------------------------------------
-# 导入 SQL Server 专用初始化脚本
-# -----------------------------------------------------------------------------
-# -d rxthinkcmf... → 目标数据库
-# -i file.sql      → 执行 SQL 文件
-sqlcmd -S localhost -U sa -P root -d rxthinkcmf.thinkphp8.elevue -i document/sqlserver/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### 3. 配置 .env
-
-```ini
-[DATABASE]
-TYPE = sqlsrv                      ; 数据库类型改为 sqlsrv
-HOSTNAME = 127.0.0.1
-DATABASE = rxthinkcmf.thinkphp8.elevue
-USERNAME = sa                      ; SQL Server 默认管理员
-PASSWORD = root
-HOSTPORT = 1433                    ; SQL Server 默认端口
-PREFIX = think_
-```
-
----
-
-## Oracle 初始化
-
-### 1. 创建表空间和用户
-
-```sql
--- 使用 sqlplus 连接 Oracle（system 为管理员用户，XE 为服务名）
-sqlplus system/root@localhost:1521/XE
-
--- 创建表空间（Oracle 数据存储的逻辑单元）
--- DATAFILE → 数据文件的物理路径
--- SIZE 100M → 初始大小 100MB
--- AUTOEXTEND ON NEXT 100M → 空间不足时自动扩展 100MB
-CREATE TABLESPACE "rxthinkcmf_thinkphp8_elevue"
-DATAFILE '/u01/oradata/rxthinkcmf_thinkphp8_elevue.dbf'
-SIZE 100M AUTOEXTEND ON NEXT 100M;
-
--- 创建数据库用户
--- IDENTIFIED BY → 设置密码
--- DEFAULT TABLESPACE → 指定默认表空间
-CREATE USER "root" IDENTIFIED BY "root"
-DEFAULT TABLESPACE "rxthinkcmf_thinkphp8_elevue";
-
--- 授权
--- CONNECT → 连接权限
--- RESOURCE → 创建表/视图等对象的权限
--- CREATE VIEW → 创建视图的权限
--- UNLIMITED TABLESPACE → 不限制表空间使用量
-GRANT CONNECT, RESOURCE, CREATE VIEW TO "root";
-GRANT UNLIMITED TABLESPACE TO "root";
-EXIT;
-```
-
-### 2. 导入 SQL 脚本
-
-```bash
-# -----------------------------------------------------------------------------
-# 导入 Oracle 专用初始化脚本
-# -----------------------------------------------------------------------------
-# sqlplus → Oracle 命令行工具
-# root/root@localhost:1521/XE → 用户/密码@主机:端口/服务名
-# @file.sql → 执行 SQL 文件
-sqlplus root/root@localhost:1521/XE @document/oracle/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### 3. 配置 .env
-
-```ini
-[DATABASE]
-TYPE = oracle                      ; 数据库类型改为 oracle
-HOSTNAME = 127.0.0.1
-DATABASE = rxthinkcmf.thinkphp8.elevue
-USERNAME = root
-PASSWORD = root
-HOSTPORT = 1521                    ; Oracle 默认端口
-PREFIX = think_
-```
-
----
-
-## 验证数据库
-
-无论使用哪种数据库，都可以通过以下方式验证：
-
-```bash
-# 方式一：ThinkPHP 命令行（显示版本信息，验证框架可正常加载）
-php think version
-
-# 方式二：手动测试登录接口（POST 请求 + JSON 参数）
-curl http://localhost:8000/api/login -X POST \
-  -H "Content-Type: application/json" \
-  -d '{"username":"admin","password":"123456"}'
-```
-
-各数据库直接查询验证：
-
-```bash
-# -----------------------------------------------------------------------------
-# MySQL：查询用户表记录数（验证表是否创建成功且有数据）
-# -----------------------------------------------------------------------------
-# -e → 执行 SQL 后退出
-mysql -u root -proot rxthinkcmf.thinkphp8.elevue -e "SELECT COUNT(*) FROM think_user;"
-
-# -----------------------------------------------------------------------------
-# PostgreSQL：查询用户表记录数
-# -----------------------------------------------------------------------------
-# -c → 执行 SQL 命令
-psql -U postgres -d rxthinkcmf.thinkphp8.elevue -c "SELECT COUNT(*) FROM think_user;"
-
-# -----------------------------------------------------------------------------
-# SQLite：查询用户表记录数
-# -----------------------------------------------------------------------------
-sqlite3 /www/api/runtime/database.sqlite "SELECT COUNT(*) FROM think_user;"
-
-# -----------------------------------------------------------------------------
-# SQL Server：查询用户表记录数
-# -----------------------------------------------------------------------------
-# -Q → 执行查询后退出
-sqlcmd -S localhost -U sa -P root -d rxthinkcmf.thinkphp8.elevue -Q "SELECT COUNT(*) FROM think_user;"
-
-# -----------------------------------------------------------------------------
-# Oracle：查询用户表记录数（需先进入 SQL 命令行）
-# -----------------------------------------------------------------------------
-sqlplus root/root@localhost:1521/XE
-SELECT COUNT(*) FROM think_user;
-EXIT;
-```
-
----
-
-## 默认数据
-
-导入完成后，系统包含以下初始数据：
-
-| 数据 | 说明 |
-|------|------|
-| 管理员账号 | admin / 123456 |
-| 默认角色 | 超级管理员（data_scope=1，全部数据权限） |
-| 系统菜单 | 完整的菜单和权限节点数据 |
-| 字典数据 | 性别、状态等基础字典 |
-| 系统参数 | DEFAULT_PASSWORD 等系统参数 |
-| 城市数据 | 全国行政区划数据 |
-
----
-
-## 常见问题
-
-### Q: 导入报错字符集问题（MySQL）
-
-```bash
-# --default-character-set=utf8mb4 → 指定字符集为 utf8mb4（支持 emoji）
-mysql -u root -proot --default-character-set=utf8mb4 rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### Q: 表已存在错误
-
-```bash
-# -----------------------------------------------------------------------------
-# 先删除旧数据库再重建（⚠️ 会清空所有数据）
-# -----------------------------------------------------------------------------
-# DROP DATABASE IF EXISTS → 如果存在则删除
-mysql -u root -proot -e "DROP DATABASE IF EXISTS \`rxthinkcmf.thinkphp8.elevue\`;"
-
-# 创建数据库（指定字符集）
-mysql -u root -proot -e "CREATE DATABASE \`rxthinkcmf.thinkphp8.elevue\` DEFAULT CHARACTER SET utf8mb4;"
-
-# 重新导入 SQL
-mysql -u root -proot rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.sql
-```
-
-### Q: PostgreSQL 导入报错
-
-确保使用 `document/postgresql/` 目录下的脚本，该脚本已针对 PostgreSQL 语法做了适配。
-
-### Q: SQLite 文件权限问题
-
-```bash
-# 664 → owner/group 可读写，others 只读
-chmod 664 /www/api/runtime/database.sqlite
-
-# 修改文件所有者为 Web 服务器用户
-chown www-data:www-data /www/api/runtime/database.sqlite
-```
+→ [2.3 配置文件与环境变量](/zh/quickstart/env-vars.html)

EasyGoAdmin_Gin_AntdVue/zh/quickstart/docker.md

@@ -1,470 +1,76 @@
 # 2.7 Docker 快速体验
 
 :::tip 概述
-Docker 方案适合快速体验项目功能，无需手动安装 PHP、MySQL 等环境。本文提供完整的 Nginx + PHP-FPM 架构配置，复制即可使用。生产环境部署请参考[第 11 章](/zh/deploy/checklist.html)。
+`deploy/docker-compose.yaml` 编排了应用、Nginx、MySQL、Redis 四个容器，一键拉起完整运行环境。适合快速体验与作为生产部署的参照。
 :::
 
-## 架构说明
+## 编排拓扑
 
-```
-浏览器 → localhost:8000 → [Nginx 容器:80] → [PHP-FPM 容器:9000] → ThinkPHP
-                                              ↕
-                                  [MySQL 容器:3306] + [Redis 容器:6379]
+```text
+浏览器
+  │
+  ├─ :8000 ──→ admin-server（应用，多阶段构建的精简镜像）
+  │                │
+  │                ├─ mysql:8.0（127.0.0.1:3306 仅回环绑定）
+  │                └─ redis:7（127.0.0.1:6379 仅回环绑定）
+  │
+  └─ :8081 ──→ nginx（只读挂载 upload 卷，直供上传文件，
+                    temp 目录封禁）
 ```
 
-## 文件结构
-
-```
-├── docker-compose.yml          # 容器编排（项目根目录）
-├── docker/
-│   ├── Dockerfile              # PHP-FPM 镜像定义
-│   ├── nginx.conf              # Nginx 站点配置
-│   └── .env.docker             # 环境变量（密码等）
-├── .env                        # 应用配置
-└── ...
-```
-
-## 快速启动
-
-项目已内置完整的 Docker 配置文件（`docker-compose.yml`、`docker/Dockerfile`、`docker/nginx.conf`），无需手动创建，直接启动即可：
+## 启动步骤
 
 ```bash
-# 从官方网站 (https://www.rxthink.cn) 下载授权源码包并解压
-cd RXThinkCMF_ThinkPhp8_EleVue
-
-# 配置应用环境变量
+# 1. 准备环境变量（与 .env.example 同款友好名）
 cp .env.example .env
-# 编辑 .env，修改数据库连接地址为 Docker 服务名（见下方说明）
+# 按需修改数据库/Redis 密码、JWT 密钥、文件域名
 
-# 启动所有服务（首次会自动构建镜像，约 2-5 分钟）
-docker-compose up -d
+# 2. 构建并启动
+cd deploy
+docker compose up -d --build
 
-# 查看运行状态
-docker-compose ps
-
-# 查看日志（确认无报错）
-docker-compose logs -f app
+# 3. 初始化数据库（首次）
+docker exec -i easygoadmin-mysql mysql -uroot -p<密码> \
+  easygoadmin.gin.elevue < ../document/mysql/easygoadmin.gin.elevue.sql
 ```
 
-:::tip 说明
-`docker-compose.yml` 使用 `${VAR:-默认值}` 语法，未配置 `.env.docker` 时自动使用默认密码（Your_Strong_Password_2024 / Your_Redis_Password_2024），适合快速体验。生产部署请参考[第 11 章](/zh/deploy/docker.html)使用 `--env-file` 指定生产密码。
-:::
+## 环境变量映射
 
-## docker-compose.yml
-
-项目根目录的 `docker-compose.yml` 内容如下（供参考，无需手动创建）：
+compose 不透传 `.env` 原名，而是把友好名映射为 `APP_` 规范键：
 
 ```yaml
-# =============================================================================
-# Docker Compose — RXThinkCMF 容器编排
-# =============================================================================
-# 架构：Nginx(80) → PHP-FPM(9000) → MySQL(3306) + Redis(6379)
-#
-# 快速启动（使用默认密码）：
-#   docker-compose up -d
-#
-# 生产部署（使用 .env.docker 中的密码）：
-#   docker-compose --env-file docker/.env.docker up -d --build
-# =============================================================================
-
-version: '3.8'
-
-services:
-
-  # ===========================================================================
-  # Nginx 反向代理
-  # ===========================================================================
-  # 接收浏览器请求，静态资源直接返回，.php 请求转发给 PHP-FPM 容器
-  # ===========================================================================
-  nginx:
-    image: nginx:1.25-alpine
-    container_name: rxthinkcmf-nginx
-    ports:
-      - "${NGINX_PORT:-8000}:80"         # 宿主机端口（默认 8000），可通过环境变量覆盖
-    volumes:
-      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro   # 站点配置（只读）
-      - ./:/var/www/html:ro                                      # 项目代码（只读）
-    depends_on:
-      - app
-    networks:
-      - rxthinkcmf-net
-    restart: unless-stopped
-
-  # ===========================================================================
-  # PHP-FPM 应用服务
-  # ===========================================================================
-  # 执行 ThinkPHP 代码，处理 API 请求和业务逻辑
-  # ===========================================================================
-  app:
-    build:
-      context: .                         # 构建上下文为项目根目录
-      dockerfile: docker/Dockerfile      # Dockerfile 路径
-    container_name: rxthinkcmf-app
-    volumes:
-      - ./:/var/www/html                                          # 项目代码（可写）
-      - uploads_data:/opt/data/uploads                            # 上传文件持久化
-    environment:
-      - APP_DEBUG=${APP_DEBUG:-true}                              # 调试模式（快速体验默认开启）
-    depends_on:
-      mysql:
-        condition: service_healthy                                # 等待 MySQL 就绪
-      redis:
-        condition: service_started                                # 等待 Redis 启动
-    networks:
-      - rxthinkcmf-net
-    restart: unless-stopped
-
-  # ===========================================================================
-  # MySQL 数据库
-  # ===========================================================================
-  # 存储业务数据，首次启动自动导入 init.sql
-  # ===========================================================================
-  mysql:
-    image: mysql:8.0
-    container_name: rxthinkcmf-mysql
-    ports:
-      - "${MYSQL_PORT:-3306}:3306"       # 宿主机端口（默认 3306），可通过环境变量覆盖
-    environment:
-      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-Your_Strong_Password_2024}        # root 密码
-      MYSQL_DATABASE: ${MYSQL_DATABASE:-rxthinkcmf.thinkphp8.elevue}  # 自动创建的数据库
-      MYSQL_CHARSET: utf8mb4
-      MYSQL_COLLATION: utf8mb4_general_ci
-    volumes:
-      - mysql_data:/var/lib/mysql                                    # 数据持久化
-      - ./document/mysql/rxthinkcmf.thinkphp8.elevue.sql:/docker-entrypoint-initdb.d/init.sql:ro  # 初始化 SQL
-    command:
-      - --character-set-server=utf8mb4
-      - --collation-server=utf8mb4_general_ci
-      - --default-authentication-plugin=mysql_native_password
-    healthcheck:                         # 健康检查：确保 MySQL 可接受连接
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD:-Your_Strong_Password_2024}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s                 # MySQL 启动较慢，给 30 秒缓冲
-    networks:
-      - rxthinkcmf-net
-    restart: unless-stopped
-
-  # ===========================================================================
-  # Redis 缓存
-  # ===========================================================================
-  # 提供缓存加速，与 config/cache.php 中的 redis 驱动配合
-  # ===========================================================================
-  redis:
-    image: redis:7-alpine
-    container_name: rxthinkcmf-redis
-    ports:
-      - "${REDIS_PORT:-6379}:6379"       # 宿主机端口（默认 6379），可通过环境变量覆盖
-    command: redis-server --requirepass ${REDIS_PASSWORD:-Your_Redis_Password_2024}  # 访问密码
-    volumes:
-      - redis_data:/data                                            # 数据持久化
-    networks:
-      - rxthinkcmf-net
-    restart: unless-stopped
-
-# =============================================================================
-# 命名卷 — 持久化存储
-# =============================================================================
-# 容器删除后数据保留，彻底重置请执行：docker-compose down -v
-# =============================================================================
-volumes:
-  mysql_data:       # MySQL 数据文件
-  redis_data:       # Redis RDB 快照
-  uploads_data:     # 用户上传文件
-
-# =============================================================================
-# 内部网络
-# =============================================================================
-# 容器间通过服务名（mysql / redis / app）互相访问
-# =============================================================================
-networks:
-  rxthinkcmf-net:
-    driver: bridge
+environment:
+  APP_DATABASE_DEFAULT_HOST: ${MYSQL_HOST}
+  APP_REDIS_DEFAULT_ADDRESS: ${REDIS_ADDR}
+  APP_JWT_SECRET: ${JWT_SECRET}
+  APP_FILE_UPLOADDIR: /data/upload
+  APP_FILE_DOMAINURL: ${FILE_DOMAIN_URL}
 ```
 
-## Dockerfile
+## 卷与持久化
 
-将以下内容保存为 `docker/Dockerfile`：
+| 卷 | 挂载点 | 说明 |
+|---|---|---|
+| mysql_data | MySQL 数据目录 | 数据库持久化 |
+| redis_data | Redis 数据目录 | 缓存持久化 |
+| upload_data | 应用 /data/upload + nginx 只读挂载 | 上传文件，nginx 直供 |
 
-```dockerfile
-# =============================================================================
-# Dockerfile — PHP-FPM 应用镜像
-# =============================================================================
-# 基础镜像：PHP 8.2 + FPM
-# 构建命令：docker-compose build app
-# =============================================================================
+## 镜像要点
 
-FROM php:8.2-fpm
+`deploy/Dockerfile` 为多阶段构建：
 
-# -----------------------------------------------------------------------------
-# 1. 安装系统依赖
-# -----------------------------------------------------------------------------
-RUN apt-get update && apt-get install -y --no-install-recommends \
-        libpng-dev \                # GD 扩展 — PNG 支持
-        libjpeg-dev \               # GD 扩展 — JPEG 支持
-        libfreetype6-dev \          # GD 扩展 — 字体渲染（验证码）
-        libzip-dev \                # zip 扩展依赖
-        zip \                       # Composer 解压依赖
-        unzip \
-    && rm -rf /var/lib/apt/lists/*
+- 编译阶段：`golang:1.27-alpine`，`CGO_ENABLED=0` + 去符号表压缩体积
+- 运行阶段：`alpine:3.20` + 时区与证书，仅带二进制、config、resource
 
-# -----------------------------------------------------------------------------
-# 2. 安装 PHP 扩展
-# -----------------------------------------------------------------------------
-# pdo_mysql=MySQL驱动  mbstring=多字节  gd=图片  bcmath=高精度  zip=压缩  redis=缓存
-RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
-    && docker-php-ext-install -j$(nproc) pdo_mysql mbstring gd bcmath zip \
-    && pecl install redis \
-    && docker-php-ext-enable redis
-
-# -----------------------------------------------------------------------------
-# 3. 安装 Composer
-# -----------------------------------------------------------------------------
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
-
-# -----------------------------------------------------------------------------
-# 4. PHP 生产配置
-# -----------------------------------------------------------------------------
-RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
-    && echo '\
-date.timezone = Asia/Shanghai\n\
-memory_limit = 256M\n\
-upload_max_filesize = 50M\n\
-post_max_size = 50M\n\
-max_execution_time = 60\n\
-opcache.enable = 1\n\
-opcache.memory_consumption = 256\n\
-' >> "$PHP_INI_DIR/php.ini"
-
-# -----------------------------------------------------------------------------
-# 5. 安装项目依赖
-# -----------------------------------------------------------------------------
-WORKDIR /var/www/html
-
-COPY composer.json composer.lock ./
-RUN composer install --no-dev --optimize-autoloader --no-interaction
-
-COPY . .
-
-# -----------------------------------------------------------------------------
-# 6. 目录权限
-# -----------------------------------------------------------------------------
-RUN mkdir -p runtime uploads \
-    && chown -R www-data:www-data runtime uploads \
-    && chmod -R 775 runtime uploads
-
-EXPOSE 9000
-CMD ["php-fpm"]
-```
-
-## Nginx 配置
-
-将以下内容保存为 `docker/nginx.conf`：
-
-```nginx
-# =============================================================================
-# Nginx 配置 — ThinkPHP 8 反向代理
-# =============================================================================
-
-server {
-    listen 80;
-    server_name localhost;
-
-    # ThinkPHP 入口目录
-    root /var/www/html/public;
-    index index.php;
-
-    # URL 重写（ThinkPHP 路由必需）
-    location / {
-        if (!-e $request_filename) {
-            rewrite ^(.*)$ /index.php?s=$1 last;
-        }
-    }
-
-    # PHP-FPM 转发（"app" 是 docker-compose 中的服务名）
-    location ~ \.php$ {
-        fastcgi_pass   app:9000;
-        fastcgi_index  index.php;
-        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
-        include        fastcgi_params;
-        fastcgi_read_timeout  300;
-        fastcgi_send_timeout  300;
-    }
-
-    # 安全：禁止访问隐藏文件
-    location ~ /\. {
-        deny all;
-    }
-
-    # 安全：禁止上传目录执行 PHP
-    location ~ /uploads/.*\.php$ {
-        deny all;
-    }
-
-    # 静态资源缓存 30 天
-    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
-        expires 30d;
-        add_header Cache-Control "public, immutable";
-    }
-
-    # Gzip 压缩
-    gzip            on;
-    gzip_types      text/plain text/css application/json application/javascript text/xml;
-    gzip_min_length 1024;
-    gzip_comp_level 5;
-}
-```
-
-## 环境变量配置
-
-将以下内容保存为 `docker/.env.docker`：
-
-```ini
-# Docker 环境变量（密码等敏感信息，切勿提交 Git）
-MYSQL_ROOT_PASSWORD=Your_Strong_Password_2024
-MYSQL_DATABASE=rxthinkcmf.thinkphp8.elevue
-REDIS_PASSWORD=Your_Redis_Password_2024
-APP_DEBUG=false
-```
-
-修改项目根目录 `.env` 文件中的数据库和缓存连接：
-
-```ini
-[DATABASE]
-; 连接地址（Docker 内部使用服务名 "mysql"）
-HOSTNAME = mysql
-PASSWORD = Your_Strong_Password_2024
-
-[CACHE]
-; 连接地址（Docker 内部使用服务名 "redis"）
-REDIS_HOST = redis
-REDIS_PASSWORD = Your_Redis_Password_2024
-
-[FILE]
-; 上传目录（容器内路径）
-UPLOAD_DIR = /opt/data/uploads
-```
-
-## 访问服务
-
-启动成功后：
-
-| 服务 | 地址 | 说明 |
-|------|------|------|
-| 后端 API | http://localhost:8000 | Nginx → PHP-FPM → ThinkPHP |
-| MySQL | localhost:3306 | 用户名 root，密码 Your_Strong_Password_2024 |
-| Redis | localhost:6379 | 密码 Your_Redis_Password_2024 |
-
-验证后端是否正常：
+## 验证
 
 ```bash
-# 访问首页
-curl http://localhost:8000/
-
-# 登录获取 Token
-curl -X POST http://localhost:8000/api/login \
-  -H "Content-Type: application/json" \
-  -d '{"username":"admin","password":"123456","captcha":"618618"}'
+docker compose ps                     # 四容器 healthy
+curl http://127.0.0.1:8000/api/health # 应用就绪
 ```
 
-## 常用命令
+生产环境的完整部署清单（含 Nginx 站点配置、安全加固）见 [第 11 章 运维部署](/zh/deploy/checklist.html)。
 
-```bash
-# --------------------------------------------------------------------------
-# 服务管理
-# --------------------------------------------------------------------------
-# 启动服务
-docker-compose up -d
+## 下一步
 
-# 停止服务（保留数据）
-docker-compose down
-
-# 停止并清空所有数据（重新开始）
-docker-compose down -v
-
-# 重建镜像（Dockerfile 或 composer.json 变更后）
-docker-compose up -d --build
-
-# --------------------------------------------------------------------------
-# 日志排查
-# --------------------------------------------------------------------------
-# 查看所有日志
-docker-compose logs -f
-
-# 查看应用日志
-docker-compose logs -f app
-
-# --------------------------------------------------------------------------
-# 进入容器
-# --------------------------------------------------------------------------
-# 进入 PHP-FPM 容器
-docker-compose exec app bash
-
-# 进入 MySQL 容器
-docker-compose exec mysql bash
-
-# --------------------------------------------------------------------------
-# 数据库操作
-# --------------------------------------------------------------------------
-# 导入 SQL（手动方式）
-docker-compose exec -T mysql mysql -uroot -pYour_Strong_Password_2024 rxthinkcmf.thinkphp8.elevue < document/mysql/rxthinkcmf.thinkphp8.elevue.sql
-
-# 进入 MySQL 命令行
-docker-compose exec mysql mysql -uroot -pYour_Strong_Password_2024 rxthinkcmf.thinkphp8.elevue
-
-# --------------------------------------------------------------------------
-# ThinkPHP 命令
-# --------------------------------------------------------------------------
-# 清除缓存
-docker-compose exec app php think clear
-
-# 查看路由
-docker-compose exec app php think route:list
-```
-
-## 常见问题
-
-### 端口被占用
-
-```bash
-# Windows 查看占用端口的进程
-netstat -ano | findstr :8000
-
-# Linux/Mac
-lsof -i :8000
-
-# 解决方案：修改 docker-compose.yml 中的端口映射
-# ports:
-#   - "8080:80"    # 改为 8080
-```
-
-### 数据库连接失败
-
-确认 `.env` 中 `[DATABASE]` 下 `HOSTNAME = mysql`（Docker 服务名），不是 `127.0.0.1`。
-
-### 容器启动后立即退出
-
-```bash
-# 查看退出原因
-docker-compose logs app
-
-# 常见原因：
-# 1. PHP 扩展缺失 → 检查 Dockerfile 中的 docker-php-ext-install
-# 2. 目录权限问题 → 确认 runtime 和 uploads 目录可写
-# 3. composer install 失败 → 检查网络或镜像源
-```
-
-### 重新开始
-
-```bash
-# 删除所有容器、网络、数据卷，完全重来
-docker-compose down -v
-docker-compose up -d --build
-```
-
-## 相关文档
-
-- [生产部署](/zh/deploy/docker.html) — 生产环境完整方案
-- [后端启动](/zh/quickstart/backend-start.html) — 不用 Docker，手动启动
-- [数据库初始化](/zh/quickstart/database-init.html) — 手动导入 SQL
+→ [2.8 常见问题 FAQ](/zh/quickstart/faq.html)

EasyGoAdmin_Gin_AntdVue/zh/quickstart/env-vars.md

@@ -1,264 +1,69 @@
-# 2.5 环境变量配置
+# 2.3 配置文件与环境变量
 
 :::tip 概述
-项目使用 `.env` 文件管理环境变量，支持开发、测试、生产等多环境切换。配置优先级：`.env` > `config/*.php` > 代码默认值。
+配置以 `config/config.yaml` 为基，任意键可被环境变量覆盖（12-Factor 风格）。开发期改 YAML，生产期用环境变量注入敏感项。
 :::
 
-## .env 文件结构
+## 配置节总览
 
-项目 `.env` 文件采用 INI 分组格式，每个分组对应一个 `config/*.php` 配置文件：
+| 配置节 | 职责 |
+|---|---|
+| server | 监听地址（默认 `:8000`） |
+| logger | 日志级别、控制台开关、文件目录 |
+| database | GORM 连接（driver/host/port/username/password/dbname/params/连接池） |
+| redis | 缓存连接（为空降级内存） |
+| jwt | 密钥、签发者、双令牌有效期 |
+| captcha | 验证码字符集、尺寸、干扰参数、万能码 |
+| rateLimit | 限流开关、窗口、普通/认证接口配额 |
+| operationLog | 操作日志总开关与查询类记录开关 |
+| job | 日志保留天数、执行锁 TTL |
+| tenant | 超管新增租户级数据的默认归属 |
+| app | 时区、演示模式 demo、生产模式 prod |
+| api | 受信代理、请求体上限、文档/指标端点开关 |
+| cors | 允许来源 |
+| file | 上传根目录、访问域名、扩展名与大小限制 |
+| generator | 生成器开关、菜单挂载父级、覆盖策略 |
+| ip2region | 归属地库文件路径 |
 
-```ini
-; =============================================================================
-; .env 环境变量配置文件
-; =============================================================================
-; 格式：INI 分组格式，[分组] 下的键值对通过 env() 函数读取
-; 优先级：.env > config/*.php > 代码默认值
-; =============================================================================
+完整键值说明见 [附录 C 配置项速查](/zh/appendix/config-reference.html)。
 
-; 全局开关（不属于任何分组）
-APP_DEBUG = true                        ; 调试模式（开发 true，生产 false）
+## 环境变量覆盖规则
 
-[APP]
-DEFAULT_TIMEZONE = Asia/Shanghai        ; 默认时区
-DEMO = false                            ; 演示模式（true=拦截所有写操作）
-SHOW_ERROR_MSG = true                   ; 显示错误详情（生产环境设为 false）
+键名 = **配置路径大写、点换下划线、加 `APP_` 前缀**，仅覆盖 YAML 中已存在的键，空值视为未设置：
 
-[DATABASE]
-TYPE = mysql                            ; 数据库类型（mysql / pgsql / sqlsrv / oracle / sqlite）
-HOSTNAME = 127.0.0.1                    ; 数据库服务器地址
-DATABASE = rxthinkcmf.thinkphp8.elevue  ; 数据库名
-USERNAME = root                         ; 用户名
-PASSWORD = root                         ; 密码
-HOSTPORT = 3306                         ; 端口
-CHARSET = utf8mb4                       ; 字符集（支持 emoji）
-DEBUG = true                            ; SQL 调试（显示执行的 SQL 语句）
-PREFIX = think_                         ; 表前缀
-
-[JWT]
-SECRET = rxthinkcmf_jwt_secret_key_2024 ; 签名密钥（生产环境务必修改）
-ACCESS_TTL = 7200                       ; access_token 有效期（秒），默认 2 小时
-REFRESH_TTL = 604800                    ; refresh_token 有效期（秒），默认 7 天
-ISSUER = rxthinkcmf                     ; 签发者标识
-
-[FILE]
-UPLOAD_DIR = D:\xampp8.2\htdocs\RXThinkCMF_ThinkPhp8_EleVue\uploads      ; 上传根目录（绝对路径）
-DOMAIN_URL = http://file.thinkphp8.elevue  ; 文件访问域名
-IMAGE_EXT = gif,jpg,jpeg,png,bmp,webp,svg ; 允许的图片后缀
-FILE_EXT = gif,jpg,jpeg,png,bmp,webp,svg,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv,mp3,mp4,sql,js,css ; 允许的文件后缀
-MAX_SIZE = 10                           ; 单文件最大大小（MB）
-
-[CACHE]
-DRIVER = file                           ; 缓存驱动（file=文件，redis=Redis）
-REDIS_HOST = 127.0.0.1                  ; Redis 地址（driver=redis 时生效）
-REDIS_PORT = 6379                       ; Redis 端口
-REDIS_PASSWORD =                        ; Redis 密码（无密码留空）
-REDIS_DB = 0                            ; Redis 数据库编号
-REDIS_PREFIX = rx:                      ; 缓存键前缀
-
-[CORS]
-ALLOW_ORIGIN = *                        ; 允许的来源（* = 所有）
-
-[API]
-CAMEL_SNAKE_CONVERT = true              ; 驼峰/下划线自动转换
-
-[CAPTCHA]
-CAPTCHA_BYPASS_CODE =                   ; 万能验证码（开发用，生产务必留空）
-CAPTCHA_LENGTH = 6                      ; 验证码字符长度（4-6位）
-CAPTCHA_EXPIRE = 300                    ; 验证码过期时间（秒）
-
-[LANG]
-default_lang = zh-cn                    ; 默认语言
+```text
+database.default.host     → APP_DATABASE_DEFAULT_HOST
+redis.default.pass        → APP_REDIS_DEFAULT_PASS
+jwt.secret                → APP_JWT_SECRET
+app.prod                  → APP_APP_PROD
 ```
 
-## 配置项详解
+覆盖在启动时由 `utility/config` 叠加生效。
 
-### 应用配置 `[APP]`
+## .env.example
 
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认时区 |
-| `DEMO` | `false` | 演示模式，开启后拦截所有写操作 |
-| `SHOW_ERROR_MSG` | `true` | 是否显示错误详情，生产环境设为 `false` |
-
-全局变量（不属于任何分组）：
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `APP_DEBUG` | `true` | 调试模式，生产环境设为 `false` |
-
-### 数据库配置 `[DATABASE]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `TYPE` | `mysql` | 数据库类型：mysql / pgsql / sqlsrv / oracle / sqlite |
-| `HOSTNAME` | `127.0.0.1` | 数据库主机 |
-| `DATABASE` | - | 数据库名称（SQLite 为文件路径） |
-| `USERNAME` | `root` | 数据库用户名 |
-| `PASSWORD` | - | 数据库密码 |
-| `HOSTPORT` | `3306` | 数据库端口 |
-| `CHARSET` | `utf8mb4` | 字符集 |
-| `DEBUG` | `true` | 是否开启 SQL 调试 |
-| `PREFIX` | `think_` | 表前缀 |
-
-### JWT 配置 `[JWT]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `SECRET` | 内置默认值 | 签名密钥，**生产环境务必修改** |
-| `ACCESS_TTL` | `7200` | access_token 有效期（秒），默认 2 小时 |
-| `REFRESH_TTL` | `604800` | refresh_token 有效期（秒），默认 7 天 |
-| `ISSUER` | `rxthinkcmf` | 签发者标识 |
-
-### 文件上传配置 `[FILE]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `UPLOAD_DIR` | - | 上传根目录（绝对路径） |
-| `DOMAIN_URL` | - | 文件访问域名 |
-| `IMAGE_EXT` | `gif,jpg,jpeg,png,bmp,webp,svg` | 允许的图片后缀 |
-| `FILE_EXT` | 多种后缀 | 允许的文件后缀 |
-| `MAX_SIZE` | `10` | 单文件最大大小（MB） |
-
-### 缓存配置 `[CACHE]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `DRIVER` | `file` | 缓存驱动：`file` 或 `redis` |
-| `REDIS_HOST` | `127.0.0.1` | Redis 主机（driver=redis 时生效） |
-| `REDIS_PORT` | `6379` | Redis 端口（driver=redis 时生效） |
-| `REDIS_PASSWORD` | - | Redis 密码 |
-| `REDIS_DB` | `0` | Redis 数据库编号 |
-| `REDIS_PREFIX` | `rx:` | 缓存键前缀 |
-
-### CORS 配置 `[CORS]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `ALLOW_ORIGIN` | `*` | 允许的来源，`*` 表示所有 |
-
-### API 配置 `[API]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `CAMEL_SNAKE_CONVERT` | `true` | 驼峰/下划线自动转换开关 |
-
-### 验证码配置 `[CAPTCHA]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `CAPTCHA_BYPASS_CODE` | （空） | 万能验证码，跳过验证。仅用于开发调试，**生产环境务必留空** |
-| `CAPTCHA_LENGTH` | `6` | 验证码字符长度（4-6位） |
-| `CAPTCHA_EXPIRE` | `300` | 验证码过期时间（秒），默认 5 分钟 |
-| `CAPTCHA_RATE_WINDOW` | `60` | 防刷窗口期（秒） |
-| `CAPTCHA_RATE_LIMIT` | `20` | 窗口期内最大获取次数 |
-| `CAPTCHA_CHARS` | `ABCDEFGHJKLMNPQRSTUVWXYZ2346789` | 字符集（已排除 0O、1lI 等易混淆字符） |
-| `CAPTCHA_FONT_PATH` | `static/fonts/Vera.ttf` | 字体路径 |
-| `CAPTCHA_IMAGE_WIDTH` | `160` | 图片宽度（像素） |
-| `CAPTCHA_IMAGE_HEIGHT` | `50` | 图片高度（像素） |
-| `CAPTCHA_FONT_SIZE` | `28` | 字体大小 |
-| `CAPTCHA_NOISE_LINES` | `8` | 干扰线数量 |
-| `CAPTCHA_NOISE_DOTS` | `500` | 噪点数量 |
-
-### 国际化配置 `[LANG]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `default_lang` | `zh-cn` | 默认语言 |
-
-### 代码生成器配置 `[GENERATOR]`
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `PARENT_MENU_ID` | `189` | 生成模块的父菜单ID |
-| `APP_NAME` | `tool` | 模块应用名（影响路由前缀和前端目录） |
-
-## 多环境配置
-
-### 开发环境
-
-```ini
-; 开发环境配置（调试开启，使用文件缓存）
-APP_DEBUG = true                        ; 开启调试模式
-
-[APP]
-SHOW_ERROR_MSG = true                   ; 显示错误详情
-
-[DATABASE]
-DEBUG = true                            ; 显示执行的 SQL
-
-[CACHE]
-DRIVER = file                           ; 使用文件缓存（无需 Redis）
-```
-
-### 生产环境
-
-```ini
-; 生产环境配置（调试关闭，使用 Redis 缓存）
-APP_DEBUG = false                       ; 关闭调试模式
-
-[APP]
-SHOW_ERROR_MSG = false                  ; 不显示错误详情（防止泄露）
-
-[DATABASE]
-DEBUG = false                           ; 不显示 SQL
-
-[CACHE]
-DRIVER = redis                          ; 使用 Redis 缓存
-REDIS_HOST = 127.0.0.1                  ; Redis 地址
-REDIS_PORT = 6379                       ; Redis 端口
-REDIS_PASSWORD = <你的Redis密码>         ; Redis 密码
-
-[JWT]
-SECRET = <随机生成的强密钥>              ; 签名密钥（必须修改）
-
-[CORS]
-ALLOW_ORIGIN = https://admin.example.com  ; 限制为实际域名
-```
-
-### 生成强密钥
+根目录 `.env.example` 是环境变量样例，复制为 `.env` 后按需修改：
 
 ```bash
-# Linux / macOS：使用 OpenSSL 生成 32 字节随机 Base64 字符串
-openssl rand -base64 32
-
-# PHP：生成 32 字节随机十六进制字符串（64 个字符）
-# random_bytes(32) → 32 字节密码学安全随机数
-# bin2hex() → 转为十六进制字符串
-php -r "echo bin2hex(random_bytes(32));"
+cp .env.example .env
 ```
 
-## 前端环境变量
+样例包含数据库、Redis、JWT 密钥、文件域名等友好名映射（docker-compose 经 `environment` 块把友好名转成 `APP_` 规范键）。
 
-前端使用 Vite 的环境变量机制，配置文件位于 `ui/` 目录：
+:::warning 硬检查
+新增配置键必须同步更新 `.env.example`——`make check-config`（`cmd/api -check-config`）会硬检查两者的键一致性，不一致直接失败。
+:::
 
-### `.env.development`（开发环境）
+## 生产模式要点
 
-```bash
-# API 接口基础路径（Vite 代理会将此路径的请求转发到后端）
-VITE_GLOB_API_URL=/api
+`app.prod=true` 时启动校验将拒绝：
 
-# API 前缀（一般留空）
-VITE_GLOB_API_URL_PREFIX=
+- 默认或过短的 JWT 密钥
+- 非空的验证码万能码（captcha.bypassCode）
+- 未关闭的代码生成器（generator.enable）
 
-# 是否启用 Mock 数据（false = 使用真实后端 API）
-VITE_USE_MOCK=false
-```
+生产部署必须开启 prod 并关闭文档端点（`api.docs=false`）。详见 [11.8 安全加固清单](/zh/deploy/security.html)。
 
-### `.env.production`（生产环境）
+## 下一步
 
-```bash
-# API 接口基础路径（生产环境的实际后端地址）
-VITE_GLOB_API_URL=/api
-
-# API 前缀
-VITE_GLOB_API_URL_PREFIX=
-```
-
-在代码中访问环境变量：
-
-```typescript
-// 通过 import.meta.env 访问 Vite 环境变量
-// VITE_ 前缀的变量才会被暴露给客户端代码
-const apiUrl = import.meta.env.VITE_GLOB_API_URL
-```
+→ [2.4 后端服务启动](/zh/quickstart/backend-start.html)

EasyGoAdmin_Gin_AntdVue/zh/quickstart/faq.md

@@ -1,104 +1,61 @@
 # 2.8 常见问题 FAQ
 
-## 环境相关
+:::tip 概述
+本页汇总快速入门阶段的高频问题。更多排错手段见 [11.10 故障排查手册](/zh/deploy/troubleshooting.html)。
+:::
 
-### Q: PHP 版本低于 8.2 能运行吗？
+## 启动类
 
-A: 不能。项目使用了 PHP 8.2 的强类型特性（如 `readonly` 属性、`DNF` 类型等），必须使用 PHP 8.2+。
+**Q：启动即退出，提示配置校验失败？**
 
-### Q: 缺少 PHP 扩展怎么办？
+启动是 fail-fast 的：JWT 密钥为空或过短、DSN 字段不完整都会直接退出。按提示修正 `config.yaml` 或对应 `APP_*` 环境变量。生产模式（`app.prod=true`）还会拒绝默认密钥、万能验证码与未关闭的生成器。
 
-A: 运行 `php -m` 检查已安装的扩展。缺少的扩展参考 [2.1 节](/zh/quickstart/environment.html) 安装。最常见的是缺少 `pdo_mysql` 和 `gd`。
+**Q：提示 Redis 连接失败？**
 
-### Q: Composer 安装很慢怎么办？
+Redis 是可选依赖。cache.Init 探测失败会自动降级内存模式并打告警日志，服务照常启动。需要真实 Redis 时核对 `redis.default.address/pass`。
 
-A: 配置中国镜像：
+**Q：Windows 下 `make` 命令不可用？**
 
-```bash
-# 配置阿里云 Composer 镜像（加速依赖下载）
-# -g → 修改全局配置（所有项目生效）
-# repo.packagist → 设置 Packagist 仓库镜像地址
-composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
-```
+使用 `make.bat <目标>`，两套目标完全一致。
 
-### Q: Redis 不安装可以吗？
+**Q：8000 端口被占用？**
 
-A: 可以。Redis 是可选的缓存驱动，不安装时使用 file 缓存。将 `.env` 中 `CACHE.DRIVER` 设为 `file` 即可。
+改 `server.address`（如 `:8001`），或释放占用端口。注意同步改前端代理目标。
 
-## 启动相关
+## 数据库类
 
-### Q: `php think run` 报错 "Address already in use"
+**Q：连接被拒绝 / 访问被拒绝？**
 
-A: 端口被占用，更换端口：
+确认 MySQL 已启动、账号密码与 `database.default` 一致、库已创建并导入种子脚本。
 
-```bash
-# --port → 指定监听端口（默认 8000）
-php think run --port 8080
-```
+**Q：想换 PostgreSQL / SQL Server 怎么办？**
 
-### Q: 数据库连接失败 "Connection refused"
+改 `database.default.driver` 与连接字段即可，代码零改动。已有数据用 `make migrator` 跨库搬迁，见 [7.6 数据库迁移工具](/zh/tools/db-migrate.html)。
 
-A: 检查以下几点：
-1. MySQL 服务是否启动：`systemctl status mysql`
-2. `.env` 中的数据库配置是否正确
-3. 数据库用户是否有权限：`GRANT ALL ON \`rxthinkcmf.thinkphp8.elevue\`.* TO 'root'@'localhost'`
+**Q：物理删除报错被拦截？**
 
-### Q: 登录返回 401
+这是设计行为——一切删除走软删除（`del_flag=1`），物理删除被全局钩子拦截。定时清理等特殊场景用 `WithPhysicalDelete(ctx)` 显式放行。
 
-A: 可能原因：
-1. Token 过期 → 重新登录
-2. 请求头格式错误 → 确保是 `Authorization: Bearer <token>`
-3. JWT 密钥不匹配 → 检查 `.env` 中的 `JWT.SECRET`
+## 前端类
 
-## 前端相关
+**Q：`pnpm dev` 后页面接口全部 404/代理失败？**
 
-### Q: `pnpm install` 报错
+后端未启动或端口不一致。确认 `/api/health` 可访问，并核对 `ui/.env.development` 的 `VITE_PROXY` 指向。
 
-A: 清除缓存重新安装：
+**Q：登录提示验证码错误？**
 
-```bash
-# 删除依赖目录和锁文件，重新安装
-rm -rf node_modules pnpm-lock.yaml      # 删除旧的依赖和锁文件
-pnpm install                             # 重新安装所有依赖
-```
+验证码有 300 秒有效期且一次性。开发调试可配置 `captcha.bypassCode` 万能码——但生产模式下非空万能码会被拒绝启动。
 
-### Q: 前端请求后端 404
+## 配置类
 
-A: 检查以下几点：
-1. 后端服务是否启动
-2. Vite 代理配置是否正确（`vite.config.ts` 中的 `target`）
-3. API 路径是否正确（应以 `/api` 开头）
+**Q：新增了配置键，`make check-config` 报不一致？**
 
-### Q: 页面白屏
+新增键必须同步写入 `.env.example`。这是硬检查项，两者键集合必须一致。
 
-A: 打开浏览器控制台（F12）查看错误信息，常见原因：
-1. JS 加载失败 → 检查网络请求
-2. 路由配置错误 → 检查后端菜单数据
-3. Token 过期 → 重新登录
+**Q：环境变量设置了但不生效？**
 
-## Oracle 相关
+覆盖规则：键名 = 配置路径大写、点换下划线、加 `APP_` 前缀；且**仅覆盖 YAML 中已存在的键**，空值视为未设置。例：`database.default.host` → `APP_DATABASE_DEFAULT_HOST`。
 
-### Q: ThinkPHP 连接 Oracle 需要哪个 PHP 扩展？
+**Q：上传的文件访问不到？**
 
-A: 需要 `pdo_oci` 扩展。ThinkPHP 的 Oracle 连接器通过 PDO 连接数据库（DSN 前缀 `oci:dbname=`），XAMPP 8.2 已自带 `php_pdo_oci.dll`，只需在 php.ini 中启用即可。
-
-### Q: XAMPP 下 pdo_oci 扩展加载失败怎么办？
-
-A: 按以下顺序排查：
-1. 是否安装了 Oracle Instant Client 19c（x64）并解压到固定路径
-2. 该路径是否已添加到**系统变量** PATH 中（不是用户变量）
-3. 是否安装了 VC++ 2015-2022 Redistributable（x64）
-4. `php.ini` 中 `extension=pdo_oci` 是否已去掉分号
-5. XAMPP 是否**完全关闭再启动**（不是只点 Apache 的 Start/Stop）
-
-### Q: 命令行 `php -m` 能看到 pdo_oci，但浏览器 phpinfo() 里找不到？
-
-A: Apache 作为 Windows 服务运行时，读取的是服务启动时的系统 PATH。如果在 Apache 启动**之后**才修改了 PATH 环境变量，Apache 不会感知到。解决方法：在 XAMPP 控制面板中完全停止 Apache，再重新启动。
-
-### Q: Oracle Instant Client 应该下载哪个版本？
-
-A: 推荐下载 **19c** 的 **Basic Package**（x64）。下载地址：https://www.oracle.com/database/technologies/instant-client/downloads.html
-
-### Q: 为什么 Instant Client 必须解压到固定路径？
-
-A: 因为系统 PATH 环境变量写入的是绝对路径。如果解压到桌面或下载文件夹，后续清理、移动或重命名都会导致 PATH 失效，PHP 无法加载 Oracle 客户端库。推荐路径：`C:\oracle\instantclient_19_20`。
+生产环境由 Nginx 直供 upload 目录，`file.domainUrl` 配置访问基址（不含 upload 段）。本地未配置域名时应用挂开发回退且封禁 temp 目录。详见 [7.2 上传配置详解](/zh/tools/upload-config.html)。

EasyGoAdmin_Gin_AntdVue/zh/quickstart/first-api.md

@@ -1,208 +1,79 @@
 # 2.6 第一个接口调试
 
 :::tip 概述
-本章通过实际操作，带您完成第一个 API 接口的调试，从登录获取 Token 到调用业务接口。
+本页用「获取验证码 → 登录 → 携带 Token 请求受保护接口」走一遍完整调用链，帮助你验证环境全通、理解统一响应格式。
 :::
 
-## 调试工具
-
-推荐使用以下工具进行 API 调试：
-
-- **ApiFox**：图形化 API 调试工具（https://apifox.com/）
-- **curl**：命令行工具（系统自带）
-- **浏览器开发者工具**：F12 → Network 面板
-
-## 步骤一：获取验证码
+## 第一步：获取图形验证码（公开接口）
 
 ```bash
-# GET 请求获取验证码（返回 Base64 编码的图片 + 验证码 key）
-curl http://localhost:8000/api/captcha
+curl http://127.0.0.1:8000/api/captcha
 ```
 
-响应示例：
+返回统一信封：
 
 ```json
 {
   "code": 0,
   "ok": true,
   "msg": "操作成功",
-  "data": {
-    "key": "a1b2c3d4e5f6...",
-    "image": "data:image/png;base64,iVBOR..."
-  }
+  "data": { "key": "...", "captcha": "data:image/png;base64,..." }
 }
 ```
 
-将 `key` 保存备用，`image` 是 Base64 编码的验证码图片。
+`data.key` 为验证码标识，`data.captcha` 为图片 dataURL（默认 TTF 渲染 PNG，字体缺失时降级 SVG）。`/api/captcha` 在路由声明中标记 `Public: true`，免登录即可访问。项目公开接口仅两处来源：RouteSpec 的 Public 标记，以及基础设施白名单（`/api/health`、`/swagger`、`/api.json`、`/metrics`）。
 
-## 步骤二：登录获取 Token
+## 第二步：登录换取 Token
 
 ```bash
-# -----------------------------------------------------------------------------
-# 登录接口（POST + JSON）
-# -----------------------------------------------------------------------------
-# -X POST                → 使用 POST 方法
-# -H "Content-Type: ..." → 告诉服务器请求体是 JSON 格式
-# -d '{...}'             → 发送 JSON 请求体
-#   username   → 用户名
-#   password   → 密码
-#   captchaKey → 步骤一返回的验证码 key
-#   captchaCode → 验证码图片上显示的字符
-curl -X POST http://localhost:8000/api/login \
+curl -X POST http://127.0.0.1:8000/api/login \
   -H "Content-Type: application/json" \
-  -d '{
-    "username": "admin",
-    "password": "123456",
-    "captchaKey": "a1b2c3d4e5f6...",
-    "captchaCode": "1234"
-  }'
+  -d '{"username":"admin","password":"******","key":"<上一步key>","code":"<验证码>"}'
 ```
 
-响应示例：
+请求字段（`internal/model/dto/auth.go` LoginReq）：`username`、`password` 必填；`code` + `key` 为图形验证码（key 即 captcha 接口返回的 uuid 字段值，登录必须一并提交）；`tenantCode` 留空按用户名全局定位。
 
-```json
-{
-  "code": 0,
-  "ok": true,
-  "msg": "登录成功",
-  "data": {
-    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
-    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
-    "token_type": "Bearer",
-    "expires_in": 7200,
-    "user": {
-      "id": 1,
-      "username": "admin",
-      "realname": "管理员",
-      "avatar": ""
-    }
-  }
-}
-```
+登录成功后 `data` 为 OAuth2 风格令牌对（LoginRes）：
 
-将 `access_token` 保存备用。
+| 字段 | 说明 |
+|---|---|
+| access_token | 访问令牌（默认 2 小时），后续请求携带 |
+| refresh_token | 刷新令牌（默认 7 天），过期后经 `/api/oauth2/token` 兑换新令牌 |
+| expires_in | access 有效期（秒） |
+| token_type | 令牌类型，固定 Bearer |
 
-## 步骤三：调用业务接口
+令牌机制详见 [8.7 Token 使用说明](/zh/api-spec/token.html)。
 
-使用 Token 调用需要认证的接口：
+## 第三步：访问受保护接口
 
 ```bash
-# -----------------------------------------------------------------------------
-# 获取用户分页列表（GET + Authorization 头）
-# -----------------------------------------------------------------------------
-# pageNo=1\&pageSize=10 → 分页参数（\& 是 bash 转义，防止 & 被解释为后台运行符）
-# -H "Authorization: Bearer <token>" → 在请求头中携带 JWT Token
-curl http://localhost:8000/api/user/page?pageNo=1\&pageSize=10 \
-  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+curl http://127.0.0.1:8000/api/index/getUser \
+  -H "Authorization: Bearer <access_token>"
 ```
 
-响应示例：
+带合法 Token 返回当前用户信息；不带或过期返回 401 信封。
+
+## 响应信封约定
+
+所有接口（含错误）都遵循统一结构：
 
 ```json
-{
-  "code": 0,
-  "ok": true,
-  "msg": "操作成功",
-  "data": {
-    "records": [
-      {
-        "id": 1,
-        "username": "admin",
-        "realname": "管理员",
-        "status": 1,
-        "statusText": "启用",
-        "createTime": "2026-01-01 00:00:00"
-      }
-    ],
-    "total": 1,
-    "size": 10,
-    "current": 1,
-    "pages": 1
-  }
-}
+{ "code": 0, "ok": true, "msg": "操作成功", "data": {} }
 ```
 
-## 步骤四：测试其他接口
+| 字段 | 说明 |
+|---|---|
+| code | 0 成功；非 0 为业务/系统错误码 |
+| ok | 是否成功（布尔捷径） |
+| msg | 提示信息 |
+| data | 业务数据（无数据时为 null） |
 
-```bash
-# -----------------------------------------------------------------------------
-# 获取当前登录用户信息
-# -----------------------------------------------------------------------------
-curl http://localhost:8000/api/index/getUser \
-  -H "Authorization: Bearer <your_token>"
+完整约定见 [8.1 统一响应格式](/zh/api-spec/response.html)。
 
-# -----------------------------------------------------------------------------
-# 获取当前用户的菜单列表（用于前端动态路由）
-# -----------------------------------------------------------------------------
-curl http://localhost:8000/api/index/getMenus \
-  -H "Authorization: Bearer <your_token>"
+## 用 Swagger 核对
 
-# -----------------------------------------------------------------------------
-# 获取字典项（gender = 性别字典的编码）
-# -----------------------------------------------------------------------------
-curl http://localhost:8000/api/dict/item/getDictItemList/gender \
-  -H "Authorization: Bearer <your_token>"
+`api.docs=true` 时可访问 `http://127.0.0.1:8000/swagger` 查看全部端点——它与路由元数据同源生成，包含每个接口的权限码与公开标记。
 
-# -----------------------------------------------------------------------------
-# 刷新 Token（access_token 过期后，用 refresh_token 换取新的）
-# -----------------------------------------------------------------------------
-curl -X POST http://localhost:8000/api/oauth2/token \
-  -H "Content-Type: application/json" \
-  -d '{"grant_type": "refresh_token", "refresh_token": "<your_refresh_token>"}'
-```
+## 下一步
 
-## 错误响应示例
-
-### 401 未授权（Token 缺失或无效）
-
-```json
-{
-  "code": 401,
-  "ok": false,
-  "msg": "未提供认证令牌",
-  "data": null
-}
-```
-
-### 403 禁止访问（权限不足）
-
-```json
-{
-  "code": 403,
-  "ok": false,
-  "msg": "无访问权限：用户列表",
-  "data": null
-}
-```
-
-### 422 参数验证失败
-
-```json
-{
-  "code": 1,
-  "ok": false,
-  "msg": "参数验证失败",
-  "data": {
-    "username": "用户名不能为空"
-  }
-}
-```
-
-## ApiFox 配置建议
-
-1. 创建环境，设置变量：
-   - `base_url` = `http://localhost:8000`
-   - `token` = 登录后填入 access_token
-
-2. 在请求头中使用变量：
-   - `Authorization` = `Bearer {{token}}`
-
-3. 登录请求的「后置操作」中添加脚本自动保存 Token：
-   ```javascript
-   // 解析响应 JSON
-   var response = pm.response.json();
-   // 登录成功时自动将 access_token 保存到环境变量
-   if (response.code === 0) {
-       pm.environment.set("token", response.data.access_token);
-   }
-   ```
+→ [2.7 Docker 快速体验](/zh/quickstart/docker.html)

EasyGoAdmin_Gin_AntdVue/zh/quickstart/frontend-start.md

@@ -1,191 +1,57 @@
-# 2.3 前端服务启动
+# 2.5 前端服务启动
 
 :::tip 概述
-本章指导您启动前端开发服务器，包括依赖安装、环境配置和 Vite 开发服务器启动。
+前端为独立 Vite 工程（`ui/`），开发端口 8001，`/api` 请求代理到后端 8000。前后端并行启动即可联调。
 :::
 
-## 步骤一：安装依赖
+## 启动命令
 
 ```bash
-# 进入前端项目目录
 cd ui
-
-# -----------------------------------------------------------------------------
-# 安装依赖（推荐 pnpm — 速度快、磁盘占用少）
-# -----------------------------------------------------------------------------
-# install → 从 pnpm-lock.yaml 精确安装所有依赖
-pnpm install
-
-# 如果没有 pnpm，也可以使用 npm
-npm install
+pnpm install    # 首次运行安装依赖
+pnpm dev        # 启动开发服务器
 ```
 
-:::warning Node.js 版本
-前端项目要求 Node.js >= 18，推荐使用 22.x。可通过 `node -v` 检查版本。
-:::
+浏览器访问 `http://localhost:8001`。
 
-## 步骤二：配置环境变量
+## 开发代理
 
-前端有两个环境配置文件：
-
-### `.env.development`（开发环境）
-
-```bash
-# 服务端口
-VITE_PORT = 8001
-
-# 公共基础路径
-VITE_PUBLIC_PATH = /
-
-# 代理配置（JSON 数组格式：[["前缀","目标地址"]]）
-VITE_PROXY = [["/api","http://admin.thinkphp8.elevue/api"]]
-
-# API 接口基础路径（留空，由代理处理）
-VITE_GLOB_API_URL =
-
-# API 前缀
-VITE_GLOB_API_URL_PREFIX = /api
-
-# 上传接口地址
-VITE_GLOB_UPLOAD_URL = /api/upload
-
-# 图片访问地址
-VITE_GLOB_IMG_URL = http://file.thinkphp8.elevue
-
-# 是否启用 Mock 数据（false = 使用真实后端 API）
-VITE_USE_MOCK = false
-```
-
-### `.env.production`（生产环境）
-
-```bash
-# 公共基础路径
-VITE_PUBLIC_PATH = /
-
-# 是否在生产环境删除 console
-VITE_DROP_CONSOLE = true
-
-# API 接口基础路径（留空，由 Nginx 代理处理）
-VITE_GLOB_API_URL =
-
-# API 前缀
-VITE_GLOB_API_URL_PREFIX = /api
-
-# 上传接口地址
-VITE_GLOB_UPLOAD_URL = /api/upload
-
-# 图片访问地址
-VITE_GLOB_IMG_URL = http://file.thinkphp8.elevue
-
-# 是否启用 gzip 压缩
-VITE_BUILD_COMPRESS = gzip
-
-# 压缩后是否删除原文件
-VITE_BUILD_COMPRESS_DELETE_ORIGIN_FILE = false
-```
-
-## 步骤三：启动开发服务器
-
-```bash
-# -----------------------------------------------------------------------------
-# 启动 Vite 开发服务器（支持热更新 — 修改代码后浏览器自动刷新）
-# -----------------------------------------------------------------------------
-pnpm dev
-
-# 或使用 npm
-npm run dev
-```
-
-启动成功后会看到：
+`ui/.env.development` 配置了跨域代理：
 
 ```text
-  VITE v3.2.x  ready in 1234 ms
-
-  ➜  Local:   http://localhost:8001/
-  ➜  Network: http://192.168.1.100:8001/
+VITE_PROXY=[["/api", "http://127.0.0.1:8000/api"]]
 ```
 
-## 步骤四：配置 API 代理
+页面发起的 `/api/**` 请求由 Vite 转发到本地 8000 后端，开发期无需处理跨域。接口前缀由 `VITE_GLOB_API_URL_PREFIX=/api` 统一管理。
 
-开发环境下，前端通过 Vite 代理将 `/api` 请求转发到后端服务。
+## 其他环境变量
 
-在 `vite.config.ts` 中配置代理：
+| 键 | 说明 |
+|---|---|
+| VITE_PORT | 开发端口（8001） |
+| VITE_USE_MOCK | mock 开关（默认关闭） |
+| VITE_DROP_CONSOLE | 构建时移除 console |
+| VITE_BUILD_COMPRESS | 构建压缩方式（gzip / brotli / none） |
 
-```typescript
-// ui/vite.config.ts
-server: {
-  port: 8001,                                       // 开发服务器端口（对应 VITE_PORT）
-  proxy: {
-    '/api': {
-      target: 'http://admin.thinkphp8.elevue/api',  // 后端服务地址（对应 VITE_PROXY）
-      changeOrigin: true,                            // 开启跨域（修改请求头的 Origin）
-      rewrite: (path) => path,                       // 保持路径不变（不做路径替换）
-    },
-  },
-}
-```
+生产环境变量见 `ui/.env.production`。
 
-确保后端服务已启动（`php think run`），然后访问 `http://localhost:8001`。
-
-## 步骤五：验证前后端联调
-
-1. 打开浏览器访问 `http://localhost:8001`
-2. 应该看到登录页面
-3. 输入默认账号 `admin` / `123456`
-4. 登录成功后进入控制台页面
-
-:::tip 代理原理
-浏览器 → `http://localhost:8001/api/login` → Vite 代理 → `http://admin.thinkphp8.elevue/api/login` → 后端处理
-:::
-
-## 构建生产版本
+## 常用命令
 
 ```bash
-# -----------------------------------------------------------------------------
-# 构建生产版本（Vite 会压缩代码、Tree-shaking、分包）
-# -----------------------------------------------------------------------------
-# build → 输出到 ui/dist/ 目录
-pnpm build
-
-# -----------------------------------------------------------------------------
-# 预览构建结果（本地启动一个静态文件服务器预览 dist/ 内容）
-# -----------------------------------------------------------------------------
-pnpm preview
+pnpm dev             # 开发
+pnpm build           # 生产构建
+pnpm type:check      # TypeScript 类型检查
+pnpm lint:eslint     # ESLint 检查
 ```
 
-构建完成后，`ui/dist/` 目录包含可部署的静态文件。
+## 登录验证
 
-## 常见问题
+前后端都启动后，访问前端登录页，用数据库内置账号登录。若后端未启动，页面接口会报代理失败——先确认后端 `/api/health` 正常。
 
-### 1. `pnpm install` 报错
+## 前端登录方式
 
-```bash
-# -----------------------------------------------------------------------------
-# 清除缓存重新安装（修复依赖冲突或缓存损坏）
-# -----------------------------------------------------------------------------
-# rm -rf → 递归强制删除（node_modules 和 lockfile）
-rm -rf node_modules pnpm-lock.yaml
-pnpm install
-```
+登录页内置四种表单：账号密码、手机验证码、扫码登录、注册。开发环境均可使用（验证码能力依赖后端 captcha 模块）。
 
-### 2. 端口 8001 被占用
+## 下一步
 
-修改 `.env.development` 中的 `VITE_PORT` 或 `vite.config.ts` 中的 `server.port`：
-
-```typescript
-server: {
-  port: 8002,  // 改为其他端口（如 8002、8003 等）
-}
-```
-
-### 3. API 请求 404
-
-检查后端服务是否启动，以及代理配置是否正确：
-
-```bash
-# 确认后端在运行（直接请求后端登录接口）
-# -X POST → POST 方法
-# -H      → 设置 Content-Type 为 JSON
-# -d      → 发送 JSON 请求体
-curl http://admin.thinkphp8.elevue/api/login -X POST -H "Content-Type: application/json" -d '{"username":"admin","password":"123456"}'
-```
+→ [2.6 第一个接口调试](/zh/quickstart/first-api.html)