How to troubleshoot and fix errors after AnQiCMS installation fails?

As a senior CMS website operation person, I know that the stable operation of the website and efficient content management are the foundation of business success.AnQiCMS with its efficient, concise architecture in Go language and rich enterprise-level features, has won the favor of many users.However, even the most excellent system may encounter various unexpected problems during the installation and deployment process.When AnQiCMS installation fails, this may not only delay the progress of going online, but also affect the subsequent operation plan.Therefore, it is crucial to master a systematic approach to troubleshooting and repair.

This article aims to provide detailed troubleshooting and repair guidance for website operators who encounter installation problems with AnQiCMS, helping you efficiently locate and solve problems to ensure the smooth launch of the system.

Understanding the installation process and common obstacles

The installation of AnQiCMS usually involves several core steps: downloading the installation package, uploading and extracting, configuring the runtime environment (including web servers such as Nginx/Apache, database MySQL), running the program and performing initial settings.Any oversight in any stage can lead to installation failure.Common installation obstacles mainly include improper environment configuration, insufficient permissions, port conflicts, and database connection exceptions.

Initial confirmation of the system environment

Before starting the in-depth troubleshooting, first confirm that your server environment meets the basic requirements of AnQiCMS.AnQiCMS supports Windows 10, Windows 11, Windows Server 2016 and above versions, as well as x86-based Linux distributions such as Ubuntu, CentOS, Red Hat, Debian, and is also compatible with MacOS.For source code compilation installation, you need GoLang 1.13 or higher version, as well as MySQL 5.6.35 or higher version.Ensure these basic conditions are met to effectively avoid many compatibility issues.

File integrity and permission check

The downloaded installation package may be damaged due to network fluctuations or other reasons. It is recommended to verify the file before uploading or after unpacking.At the same time, the AnQiCMS program files and their directories need to have sufficient read and write execution permissions./www/wwwroot/anqicms.com) and its subdirectories need to grant access to the web server user (such aswwwUser read and write permissions, ensure that the program can create log files, cache files, and access static resources. Insufficient permissions often lead to the program failing to start or initialize.

Panel installation troubleshooting for Baota Panel

Baota panel is a popular server management tool that simplifies the deployment of AnQiCMS. When encountering problems while installing AnQiCMS through Baota panel, the following points are worth focusing on:

First, confirm that you are using Potata Panel 7.9.3 or a higher version, which directly affects the convenience of Go project deployment./www/wwwroot/yourdomain.com/anqicmsand whether the 'project port' is set to the default8001or any other unused port you specify. The running user should choosewwwand check 'startup' to ensure it runs permanently.

Secondly, the reverse proxy configuration of Nginx or Apache is a critical step. For Nginx, you need to change the running directory in the site settings to/publicConfigure the Nginx pseudo-static rules. Please refer to the official documentation for the Nginx configuration code to ensureproxy_passpoint to the running port of AnQiCMS. For example:

location @AnqiCMS {
    proxy_pass https://en.anqicms.com;
    proxy_set_header   Host             $host;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
}
error_page 404 =200  @AnqiCMS;
location / {
   try_files $uri $uri/index.html @AnqiCMS;
}

For Apache, pseudo-static rules are usually set through reverse proxy settings, pointing the target URL to the listening port of AnQiCMS, for examplehttps://en.anqicms.com. Incorrect web server configuration will cause the front end to be unable to access the AnQiCMS service.

Troubleshooting Docker installation issues

Install AnQiCMS via Docker (using 1Panel or aaPanel) provides stronger isolation and convenience, but it may also encounter unique issues.

The core troubleshooting point lies in the running status and port mapping of Docker containers. First, check if the Docker image was successfully pulled, and whether the used image name isanqicms/anqicms:latestAfter the container is created, confirm that its status is "running". Port mapping is a common source of problems in Docker deployments, be sure to ensure that the container's8001Port is correctly mapped to an unused port on the host machine, for example8001:8001. If the host port is occupied, you can try using a different port.

Moreover, in the Docker environment, it is usually necessary to use additional reverse proxy to forward external domain traffic to the mapped ports of Docker containers. This is similar to the Nginx/Apache configuration in the Baota panel, but onlyproxy_passThe destination is the host machine's mapped port (for example127.0.0.1:8001)

For Docker installations that depend on MySQL, such as installing AnQiCMS in Baota Docker, it is necessary to confirm that the MySQL container has been started correctly and that the correct MySQL was provided during the AnQiCMS initializationrootPassword. If the MySQL service itself fails to start or is inaccessible from the outside, the database initialization of AnQiCMS is bound to fail.

Troubleshooting command line installation issues

For Linux servers without a graphical panel, manually installing AnQiCMS via the command line requires a more detailed check of each step.

First, make sure that the AnQiCMS installation package has been properly unzipped to the specified directory, for example/www/wwwroot/anqicms.com.

Next, start the scriptstart.shand stop the scriptstop.shThe configuration and execution are crucial. Confirm that these scripts exist and have execute permissions(chmod +x start.sh stop.sh). Checkstart.shofBINPATHandBINNAMEDoes the variable match your actual path and executable file name? Most importantly, make surecrontab -ehas been added to run every minutestart.shschedule task to ensure that AnQiCMS can automatically restart after an unexpected shutdown and manually execute once after startup../start.shto run immediately.

The configuration of the web server (Nginx) is similar to that in the Baota panel, just as it needs to point the site to the AnQiCMS directory.rootdirectory to the AnQiCMS directory./publicSet up the correct reverse proxy rules to forward access to the domain to the AnQiCMS listening8001on the port.

Troubleshooting local test issues on Windows/MacOS

When performing local testing or development on Windows or MacOS, installation issues are usually more direct.

For Windows, double-clickanqicms.exeAfter that, the program will run in the background without popping up a window. If the browser cannot be accessed, first check the Windows Task Manager to confirmanqicms.exeIs the process running.The Windows firewall may also block programs from providing external services, check the firewall rules or temporarily disable the firewall for testing.If you use integrated environments such as PHPStudy (Xiao Pi), you need to configure reverse proxy according to the Nginx/Apache method and forward domain requests to the listening port of AnQiCMS.hostsfile.

MacOS users also need to install MySQL and Nginx environments themselves. Double-click the unpacked installation package.anqicmsYou can run the executable file. Domain name resolution also depends onhoststhe configuration of the file.

General installation initialization failure troubleshooting

No matter which installation method is used, when AnQiCMS is accessed for the first time in the browser, it will enter the initialization installation interface. If it fails, it is usually due to the following three reasons:

• Database account password is incorrect:This is the most common error.Please carefully check the username and password you entered for the MySQL database to ensure they are correct.MySQL installed in Baota panel or Docker has its root password usually provided in the installation details.
• Database account does not have sufficient privileges:AnQiCMS needs to create a database and tables during initialization.If the MySQL account you provide has low permissions and cannot perform these operations, the initialization will fail.CREATEandGRANTThe account with permissions, or manually create the database for AnQiCMS before initialization, and grant the MySQL user used by AnQiCMS access.
• Administrator password length or complexity is insufficient:For system security, AnQiCMS may have minimum length or complexity requirements for the administrator password.If the password set is too simple, the system will refuse.Please try to set a more complex password that meets the security policy.

Check AnQiCMS logs and port conflicts

When the AnQiCMS program fails to run normally or the web server is configured correctly but the website is still inaccessible, checking the AnQiCMS program log is a key step in locating the problem. In a manual installation environment,start.shThe script usually outputs the running log of AnQiCMS torunning.logandcheck.logIn the file, these files record error information during the startup and operation of the program.Read the logs carefully and you can find detailed clues such as database connection errors, file read failures, and configuration parsing exceptions.

Port conflict is also a common problem. AnQiCMS listens on the port by default8001Port. If this port is occupied by another program on the server, AnQiCMS will not be able to start. On Linux systems, you can uselsof -i:端口号commands (for example