AnQiCMS (AnQiCMS) has gained favor among website owners and enterprise users due to its efficient and customizable features brought by the Go language.However, even the most excellent system is bound to encounter some minor setbacks during the initial installation.As a senior website operations expert, I fully understand the importance of a smooth first-time installation experience for users.Today, let's deeply analyze the common reasons for the initialization installation failure of AnQiCMS, and provide you with a set of effective troubleshooting methods to help you easily master AnQiCMS.

AnQiCMS initialization installation failure common reasons and troubleshooting guide

Before you embark on the exciting journey of AnQiCMS, completing a smooth initial installation is a crucial step.If you encounter obstacles at this stage, don't be anxious, as this is usually due to several predictable issues.Below, we will reveal these common causes and their detailed troubleshooting strategies from multiple dimensions such as environment, deployment, and configuration.

1. Inadequate preparation or incorrect configuration of the basic environment

AnQiCMS is a system developed based on the Go language, which has clear requirements for the operating environment. Any negligence in any link may lead to installation failure.

  1. Database connection failure or insufficient permissions

    • Common reasons:This is one of the most common installation failure reasons.The database connection information (such as database address, username, password, database name) you entered on the initialization interface may be incorrect, or the database user you provided may not have sufficient permissions to create a new database or table.Moreover, if the MySQL/MariaDB service itself is not running or the remote connection is limited, it can also lead to connection failure.
    • Troubleshooting methods:
      • Verify database credentials:Carefully check the database address you entered (usually)127.0.0.1orlocalhost）、port（default as3306Database name, username, and password.Recommend logging directly into the database management tool (such as phpMyAdmin, Navicat, or via command line) to verify whether these credentials can successfully connect.
      • Check database user permissions:Ensure the user used hasCREATE/ALTER/DROP/SELECT/INSERT/UPDATE/DELETEThe core permissions, especially in the Docker environment, if MySQL is deployed using Docker, usually it needsrootto initialize the account and its password.
      • Confirm the database service status:Ensure that the MySQL or MariaDB service is running. On Linux systems, you can usesystemctl status mysqlorsystemctl status mariadbcommand to check.

  2. Port is occupied

    • Common reasons:AnQiCMS默认运行在English8001Port.If another service is already using this port on your server, AnQiCMS will not start normally.Common Docker installation scenarios where server ports and container ports are mapped incorrectly may also cause this problem.
    • Troubleshooting methods:
      • 检查端口占用：English在Linux系统上，使用命令Englishlsof -i:8001可以查看English8001Port is occupied. If it is occupied, you will see the process ID (PID) that is occupying the port.
      • Handle port conflict:If the port is occupied, you can choose:
        • Stop other services from occupying this port (kill -9 PIDcommand).
        • Modify the default port to another unoccupied port in the AnQiCMS configuration fileconfig.json(for example)8002），then restart the AnQiCMS service.
        • If it is Docker deployment, make sure your server port is mapped to the container's port.8001Port, the selected server port is not occupied.

  3. Server resources are insufficient

    • Common reasons:Although the Go language itself has low resource consumption, under extreme conditions, if the server memory is too small (for example, less than 1GB), it may not be possible to run the database and AnQiCMS service simultaneously, resulting in an interruption in the installation process.Especially when deploying in Docker, if too few resources are allocated to MySQL, it may cause it to start slowly or fail.
    • Troubleshooting methods:
      • Check system memory usage:Usefree -hCommand to view server memory usage.
      • Optimize resource allocation:If the memory is insufficient, consider upgrading the server configuration or optimizing the resource allocation of the existing services. For example, allocate enough memory to the MySQL container in Docker.

二、Installation and File Deployment Issues

Ensuring the correctness and integrity of the AnQiCMS installation files is the foundation for stable system operation.

  1. Incomplete or incorrect file upload or extraction

    • Common reasons:The downloaded installation package may be corrupted, or there may be issues such as network interruption, insufficient disk space, or other problems when uploading to the server or extracting files, resulting in missing or corrupted files.Extracting files to the wrong directory may also cause the system to fail to find critical components.
    • Troubleshooting methods:
      • Redownload and verify:Download the latest installation package from the AnQiCMS official website, and verify the file size. Upload and unzip it to the specified directory (such as the Baota panel's/www/wwwroot/yourdomain.com).
      • Check file integrity:Check if the directory exists after extractionanqicmsExecutable files,config.json/templatekey files.

  2. Configuration error in the startup script

    • Common reasons:For scenarios where manual deployment or task scheduler startup is used,start.shscript, make sure it points to the correct directory of the AnQiCMS executable file, and that the directory containsBINPATH(AnQiCMS program path) orBINNAME(AnQiCMS executable file name) configuration is incorrect, which will cause the script to be unable to find and start the AnQiCMS service.
    • Troubleshooting methods:
      • Checkstart.shScript: Openstart.shFile, ensureBINPATHThe variable points to the absolute path of the executable file of AnQiCMS, andBINNAMEThe variable matches the actual executable file name (usuallyanqicms).
      • Manually execute the test:Try to manually execute under the AnQiCMS directory./anqicmsto see if there is any error output, or use./start.shmanually start once, and observerunning.logthe output of the file (if the script is configured).

  3. File permission issue

    • Common reasons:AnQiCMS executable file does not have execution permissions (Linux/MacOS), or the AnQiCMS process does not have write permissions for some directories (such as logs, cache, upload directories), which causes the system to fail to run or save data.
    • Troubleshooting methods:
      • Assign execution permission:ForanqicmsEnsure the executable file has execution permission:chmod +x /path/to/anqicms.
      • Check directory write permission:Ensure the directory where AnQiCMS program is located and its subdirectories (especiallydata/uploads/logs等）对运行用户拥有写入权限。in the English language，it is usuallywwwuser. It can be usedchown -R www:www /path/to/anqicmsandchmod -R 755 /path/to/anqicms(or}777in the test environment）to set up.

Third, Web server configuration issues

When AnQiCMS runs as a backend service, the configuration of web servers such as Nginx or Apache plays the role of a 'gatekeeper'.

  1. Incorrect reverse proxy settings
    • Common reasons:The configuration of reverse proxy is the key to accessing AnQiCMS service when using 宝塔面板, 1Panel, or manually configuring Nginx/Apache. Common errors includeproxy_pass指向的IP地址或端口错误、Host头和X-Real-IP等转发参数缺失，或者HTTP/HTTPS配置混淆。
    • Troubleshooting methods:
      • 核对代理目标：检查Web服务器配置文件中proxy_passIs pointing tohttp://127.0.0.1:8001(or the AnQiCMS port you have modified).
      • Check the header forwarding:Ensure that the configuration includes `proxy_set_header Host $host`