安企CMS的安装-常见安装问题排查

汇总安企CMS安装过程中的常见问题及解决方案，涵盖端口被占用、数据库连接失败、页面白屏、权限错误、依赖缺失等典型场景，帮助用户快速定位并解决问题。

问题 1：端口被占用

现象：启动 AnQiCMS 后，网站无法访问。

原因：默认端口 8001 被其他程序占用。

排查方法：

# Linux / MacOS：查看 8001 端口被谁占用
lsof -i:8001

# 输出示例：
# COMMAND   PID   USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
# anqicms  7621   root    3u   IPv4  12345      0t0  TCP *:8001 (LISTEN)

# 如果显示的是其他程序，需要结束它
kill -9 7621   # 7621 是上一步查到的 PID

Windows 端口排查：

# 查看 8001 端口占用
netstat -ano | findstr :8001

# 结束占用进程（PID 为最后一列数字）
taskkill /PID 7621 /F

解决方法：修改 config.json 中的端口为其他未占用的端口（如 8002），然后重启 AnQiCMS。

{
    "server": {
        "port": 8002
    }
}

修改后需要同步更新 Nginx 反向代理配置中的 proxy_pass 端口。

问题 2：伪静态规则配置不正确

现象：访问网站首页正常，但访问内页（如文章详情、分类页面）时出现 404 Not Found。

原因：Nginx 反向代理规则配置错误或未配置。

解决方法：

1. 检查 Nginx 站点配置文件中是否包含以下规则：

location @AnqiCMS {
    proxy_pass http://127.0.0.1:8001;
    proxy_set_header   Host             $host;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
}
location / {
    try_files $uri $uri/index.html @AnqiCMS;
}

1. 确保 proxy_pass 的端口与 config.json 中的端口一致

2. 重新加载 Nginx：

nginx -t          # 测试配置是否正确
nginx -s reload   # 重新加载配置

问题 3：数据库连接失败

现象：初始化安装时提示数据库连接失败。

常见原因及解决：

测试数据库连接：

# 在服务器命令行测试
mysql -h 127.0.0.1 -u root -p -e "SELECT 1"
# 输入密码后如果返回 1，说明连接正常

问题 4：目录权限不足

现象：无法上传文件/图片，或后台提示写入失败。

原因：AnQiCMS 的 data/、cache/ 等目录没有写入权限。

解决方法：

# 设置站点目录属主为运行用户（以 www 用户为例）
chown -R www:www /data/wwwroot/anqicms

# 或临时赋予所有用户写入权限（不推荐生产环境）
chmod -R 755 /data/wwwroot/anqicms
chmod -R 777 /data/wwwroot/anqicms/data
chmod -R 777 /data/wwwroot/anqicms/cache

问题 5：AnQiCMS 启动后自动退出

现象：执行 start.sh 后进程运行几秒就消失。

排查步骤：

1. 查看运行日志：

tail -f running.log

1. 查看启动检测日志：

tail -f check.log

1. 检查配置文件 config.json 是否格式正确（JSON 语法）

2. 检查端口是否被占用（见问题 1）

3. 尝试直接运行可执行文件查看错误输出：

./anqicms
# 不要使用 nohup，直接前台运行，观察控制台输出

问题 6：升级后后台版本号未更新

现象：在后台执行系统升级后，版本号仍显示旧版本。

原因：升级后需要重启 AnQiCMS 进程。

解决方法：

1. 通过计划任务或命令行停止 AnQiCMS：

./stop.sh

1. 等待几秒后重新启动：

./start.sh

1. 刷新后台页面，查看版本号是否更新

问题 7：网站域名变更后配置更新

现象：更换域名后，网站内页链接仍指向旧域名。

解决方法：

1. 后台 → 设置 → 全局设置（/setting/system）→ 修改 网站地址 为新域名
2. 后台 → 工具 → 更新缓存（/tool/cache）→ 点击 更新缓存
3. 后台 → 功能 → 全站替换（/plugin/replace）→ 将旧域名替换为新域名

问题 8：忘记后台路径或管理员密码

现象：忘记了 /system/ 后台入口路径，或管理员密码。

解决方法：

AnQiCMS 提供了 忘记密码 重置功能：

1. 在后台登录页面点击 忘记密码
2. 选择验证方式：

1. 按照页面提示完成验证
2. 重置管理员密码

问题 9：502 Bad Gateway

现象：访问网站时 Nginx 返回 502 错误。

原因：Nginx 无法连接到 AnQiCMS 后端服务（端口 8001）。

排查步骤：

1. 检查 AnQiCMS 是否在运行：

ps -ef | grep anqicms

1. 检查 8001 端口是否在监听：

netstat -tlnp | grep 8001

1. 如果未运行，启动 AnQiCMS：

cd /path/to/anqicms && ./start.sh

1. 检查 Nginx 配置中 proxy_pass 的端口是否正确

问题 10：安装时显示”数据库已存在”

现象：初始化安装时提示数据库名称已存在。

原因：之前已安装过 AnQiCMS，数据库中已存在同名数据库。

解决方法：

❓ 上面 10 个问题都排查过了，还是不行，怎么办？还有什么方法能确定到底是哪里的问题？

当你试了各种方法还是无法解决时，可以使用逐步排除法来确定问题范围：

第一步：判断是 AnQiCMS 本身的问题还是 Nginx 的问题

# 不经过 Nginx，直接访问 AnQiCMS 的端口
curl http://127.0.0.1:8001

# 如果能返回 HTML 内容（哪怕是安装界面），说明 AnQiCMS 正常运行
# 问题出在 Nginx 配置上

# 如果连接被拒绝或超时，说明 AnQiCMS 没有正常启动
# 问题出在 AnQiCMS 进程或端口上

第二步：如果是 AnQiCMS 的问题，前台运行看错误输出

# 先停止已有的进程
./stop.sh

# 直接前台运行（注意是前台，不是后台）
# 这样所有的错误信息都会输出到终端
./anqicms

第三步：如果仍然无法确定，查看日志文件

# 查看运行日志
tail -100 running.log

# 查看启动检测日志（如果有）
tail -100 check.log

# 查看 Nginx 错误日志
tail -100 /var/log/nginx/error.log

第四步：求助于社区

将以上获取到的错误信息复制出来，加上你的版本号、操作系统信息，到微信群或 GitHub Issues 提问。提供的错误信息越完整，别人帮你解决问题的速度就越快。

❓ Nginx 配置中的 proxy_pass 端口和 config.json 中的端口一定要一致吗？

必须一致。 如果不一致，Nginx 会把请求转发到 AnQiCMS 不在监听的端口上，用户会看到 502 Bad Gateway。

# config.json 中 port = 8001
proxy_pass http://127.0.0.1:8001;  # ✅ 一致，正常工作

# config.json 中 port = 8002
proxy_pass http://127.0.0.1:8001;  # ❌ 不一致，502 错误

修改端口后需要同步修改两处：config.json 中的 port + Nginx 配置中的 proxy_pass。修改后需要重启 AnQiCMS 和重载 Nginx 才能生效。

❓ 如何区分是 Nginx 的问题还是 AnQiCMS 的问题？

一个简单的判断方法——看浏览器返回的错误页面特征：

掌握了这个判断方法，不需要专业知识也能快速定位问题所在。