Installation of AnQi CMS - Troubleshooting common installation issues

Summarize the common problems and solutions during AnQiCMS installation, covering typical scenarios such as port occupation, database connection failure, white screen on the page, permission error, and missing dependencies, to help users quickly locate and solve problems.

Problem 1: Port occupied

PhenomenonAfter starting AnQiCMS, the website cannot be accessed.

ReasonDefault port8001Occupied by other programs.

Troubleshooting method:

# 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 port troubleshooting:

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

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

Solution: Modifyconfig.jsonThe port in it should be another unused port (such as8002), then restart AnQiCMS.

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

After the modification, it is necessary to synchronize the update of the Nginx reverse proxy configuration inproxy_passon the port.

Problem 2: The pseudo-static rule configuration is incorrect

Phenomenon: The homepage of the website can be accessed normally, but when accessing the inner page (such as article details, category page) it appears404 Not Found.

Reason: Nginx reverse proxy rule configuration error or not configured.

Solution:

1. Check whether the following rules are included in the Nginx site configuration file:

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. Ensureproxy_passThe port ofconfig.jsonports are consistent

2. Reload Nginx:

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

Issue 3: Database connection failed

Phenomenon: Failed to connect to the database during initialization setup.

Common reasons and solutions:

Test database connection:

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

Issue 4: Directory permission insufficient

Phenomenon: Unable to upload file/image, or background prompts write failure.

Reason: AnQiCMS's data/、cache/ directories do not have write permissions.

Solution:

# 设置站点目录属主为运行用户（以 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

Question 5: AnQiCMS exits automatically after starting.

Phenomenon: Executestart.shThe background process disappears after running for a few seconds.

Troubleshooting steps.:

1. Check the runtime log:

tail -f running.log

1. Check the startup detection log:

tail -f check.log

1. Check the configuration fileconfig.jsonIs the format correct (JSON syntax)?

2. Check if the port is occupied (see question 1).

3. Try to directly run the executable file and check the error output.

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

Question 6: The background version number is not updated after the upgrade.

PhenomenonAfter the system upgrade is executed in the background, the version number still shows the old version.

ReasonAfter the upgrade, you need to restart the AnQiCMS process.

Solution:

1. Stop AnQiCMS through the scheduled task or command line:

./stop.sh

1. Wait a few seconds and restart:

./start.sh

1. Refresh the background page and check if the version number has been updated

Question 7: Configuration update after website domain change

PhenomenonAfter changing the domain, the internal page links of the website still point to the old domain.

Solution:

1. Background →setting→Global Settings(/setting/system)→ Modifywebsite addressFor the new domain
2. Background →Tool→Update Cache(/tool/cache)→ ClickUpdate Cache
3. Background →Feature→Replace site-wide(/plugin/replace)→ Replace the old domain with the new one

Question 8: Forgot the backend path or admin password

Phenomenon: Forgot/system/Backend entry path, or admin password.

Solution:

AnQiCMS providedForgot passwordReset feature:

1. Click on the backend login pageForgot password
2. Select the verification method:

1. Complete the verification according to the page prompts
2. Reset the administrator password

Question 9: 502 Bad Gateway

Phenomenon: Nginx returns a 502 error when accessing the website.

Reason: Nginx cannot connect to AnQiCMS backend service (port 8001).

Troubleshooting steps.:

1. Check if AnQiCMS is running:

ps -ef | grep anqicms

1. Check if port 8001 is listening:

netstat -tlnp | grep 8001

1. If not running, start AnQiCMS:

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

1. Check the Nginx configuration in:proxy_passThe port is correct:

Issue 10: When installing, it shows "The database already exists".

PhenomenonInitialization installation prompts that the database name already exists.

Reason: AnQiCMS has been installed before, and a database with the same name already exists in the database.

Solution:

❓ Have all 10 questions above been checked, and it still doesn't work? What else can you do to determine what the problem is?

When you have tried all kinds of methods and still can't solve it, you can useStep-by-step eliminationto determine the scope of the problem:

Step 1: Determine whether the problem is with AnQiCMS itself or Nginx

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

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

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

Step 2: If it is an AnQiCMS issue, run the front-end to view the error output

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

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

Step 3: If you still cannot determine the issue, check the log file

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

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

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

Step 4: Seek help from the community

Copy the error information obtained above, along with your version number and operating system information, and ask questions in the WeChat group or GitHub Issues. The more complete the error information you provide, the faster others can help you solve the problem.

❓ Must the port in the Nginx configuration's proxy_pass be consistent with the port in config.?

Yes, it must be consistent.If inconsistent, Nginx will forward the request to the port that AnQiCMS is not listening on, and the user will see a 502 Bad Gateway error.

# 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 错误

After changing the port, you need to synchronize the modification of two places:config.jsonofport+ In the Nginx configurationproxy_passAfter modificationRestart AnQiCMS and reload Nginxbefore it takes effect.

❓ How to distinguish between Nginx issues and AnQiCMS issues?

A simple method of judgment - look at the characteristics of the error page returned by the browser:

Mastered this method of judgment, no professional knowledge is needed to quickly locate the problem.