首次启动 AnQiCMS 时，需要完成初始化安装，包括配置数据库连接信息、设置管理员账号密码、指定站点名称等关键步骤，是系统正式使用前的必经环节。
何时需要初始化
以下情况需要进行初始化安装：
| 场景 | 说明 |
|---|---|
| 首次部署 | 全新安装 AnQiCMS |
| 恢复出厂状态 | 清空数据后重新安装 |
如果通过 宝塔 Docker 或 aaPanel Docker 安装，系统会自动完成初始化（默认账号 admin / 密码 123456），无需手动执行初始化流程。
初始化步骤
Step 1：启动 AnQiCMS
确保 AnQiCMS 已正常启动（见 2.2 至 2.5 节相关部署说明）。
Step 2：访问安装页面
在浏览器中访问站点域名：
arduino
http://你的域名首次访问时，系统检测到尚未初始化，会自动跳转到安装界面。
Step 3：填写配置信息
安装界面需要填写以下信息：
数据库信息
| 字段 | 必须 | 说明 |
|---|---|---|
| 数据库主机 | ✅ | MySQL 服务器地址，一般为 127.0.0.1（本机）或 Docker 容器名 |
| 数据库端口 | ✅ | MySQL 端口，默认 3306 |
| 数据库用户名 | ✅ | MySQL 用户名。推荐使用 root 或具有创建数据库权限的用户 |
| 数据库密码 | ✅ | 对应的 MySQL 密码 |
| 数据库名称 | ✅ | 系统会自动创建该名称的数据库，如 anqicms。不要与已有数据库重名 |
管理员信息
| 字段 | 必须 | 说明 |
|---|---|---|
| 管理员账号 | ✅ | 后台登录用户名 |
| 管理员密码 | ✅ | 后台登录密码（建议 8 位以上，包含字母和数字） |
网站信息
| 字段 | 必须 | 说明 |
|---|---|---|
| 网站地址 | ✅ | 网站域名，如 https://www.anqicms.com（带协议前缀） |
Step 4：提交安装
点击 提交 或 开始安装 按钮，系统会：
- 检查数据库连接是否正常
- 自动创建数据库和数据表
- 写入初始配置数据
- 创建管理员账号
- 写入默认站点设置
安装过程通常只需几秒钟。安装完成后，页面会显示安装成功提示。
安装验证
验证前台
浏览器访问网站首页，应正常显示首页内容。
验证后台
perl
http://你的域名/system/显示后台登录页面。
默认后台路径
perl
http://你的域名/system/建议 ：安装完成后，及时在后台 全局设置 中修改默认的后台入口路径，增强安全性。
默认管理员账号
账号：安装时设置的管理员账号
密码：安装时设置的管理员密码安装失败处理
如果安装过程中出现错误，常见原因及解决方法：
| 错误现象 | 可能原因 | 解决方法 |
|---|---|---|
| 数据库连接失败 | 数据库主机/端口/用户名/密码错误 | 检查 MySQL 连接信息是否正确 |
| 无法创建数据库 | 数据库用户权限不足 | 使用更高权限的账号（如 root），或提前手动创建数据库 |
| 管理员密码无效 | 密码长度或复杂度不够 | 设置 8 位以上，包含字母和数字的密码 |
| 端口被占用 | 其他程序使用了 8001 端口 | 修改 config.json 中的 port 为其他值后重启 |
重置安装
如果需要重新初始化（清空所有数据）：
bash
# 1. 停止 AnQiCMS（Linux）
./stop.sh
# 2. 删除数据库（通过 MySQL 命令行或管理工具）
# 3. 删除 data/ 目录下的缓存文件（如有）
rm -rf data/*
# 4. 重新启动 AnQiCMS
./start.sh
# 5. 浏览器访问域名，重新进入安装界面⚠️ 警告：重置安装会删除所有数据（文档、分类、用户、设置等），操作前请务必备份数据库。
❓ 安装界面填写好信息点击提交后，提示"数据库连接失败"，但我的 MySQL 确实正在运行，为什么？
这个问题的常见原因有 4 个，请逐一排查：
| 原因 | 验证方法 | 解决方法 |
|---|---|---|
| MySQL 端口不是 3306 | 在服务器执行 mysql -P 3306 -u root -p，如果连不上，说明端口不对 |
在安装界面修改端口号，或通过 `netstat -tlnp |
| MySQL 只绑定了 127.0.0.1 | `cat /etc/mysql/mysql.conf.d/mysqld.cnf | grep bind-address` |
| 数据库用户无创建数据库权限 | 用 root 之外的用户连接时常见 | 安装界面填写 root 账号，或提前用 root 手动创建数据库 |
| Docker 环境下"数据库主机"填错了 | 容器内不能直接用 127.0.0.1 访问宿主机 MySQL |
改为 host.docker.internal（或宿主机内网 IP） |
最简单的方法：在服务器上用 root 账号手动创建一个空数据库，然后在安装界面填入这个已有数据库的名称，安装程序就不会再尝试创建数据库，从而跳过权限问题。
❓ 安装成功后，页面一直显示加载中/白屏/进不去，怎么办？
这种情况通常是浏览器缓存 或Nginx 配置问题。
bash
# 第一步：检查程序是否正常运行
curl -I http://127.0.0.1:8001
# 如果返回 200/302，说明 AnQiCMS 正常
# 第二步：检查 Nginx 配置
# 确保 root 指向了 public 目录
# 确保 try_files 规则存在
# 第三步：清除浏览器缓存（一般按 Ctrl+F5 强制刷新）
# 第四步：检查浏览器控制台（F12 → Console）是否有 JS 报错也可能是安装后需要等待几秒让数据库写入完成，稍微刷新一下即可。
❓ 安装时填写的"网站地址"写错了（比如忘了加 https://），安装后还能改吗？
可以改，不需要重新安装。 安装完成后在后台修改即可：
- 登录后台 → 设置 → 全局设置 （
/setting/system） - 找到"网站地址"字段，修改为正确的地址（如
https://www.anqicms.com） - 点击保存
- 后台 → 工具 → 更新缓存 （
/tool/cache）
网站地址写错不影响网站运行，但可能会导致 Sitemap、友情链接等生成错误的链接地址，所以建议安装后第一时间检查并修正。
❓ 初始化安装时，管理员密码有没有强度要求？
| 要求 | 说明 |
|---|---|
| 最小长度 | 至少 6 位（建议 8 位以上） |
| 字符组合 | 建议字母 + 数字组合，纯数字密码容易被暴力破解 |
| 特殊字符 | 可以包含特殊字符（!@#$% 等） |
| 常见密码 | 不要使用 admin123、123456、password 等弱密码 |
推荐做法：使用密码管理器（如 1Password、Bitwarden）生成随机密码，并在后台保存好。如果忘记了密码，可以使用后台登录页的"忘记密码"功能通过文件验证或 DNS 验证来重置。