SRE Patterns — aaPanel Infrastructure

SRE Patterns — aaPanel Infrastructure

Reference knowledge for operating aaPanel-managed Linux servers with a custom observability stack.

aaPanel Directory Map

/www/wwwroot/           # web roots (one dir per domain/app)
/www/wwwlogs/           # nginx access + error logs
/www/server/
  nginx/
    conf/               # global nginx config
    vhost/              # per-domain vhosts (aaPanel-managed — do not edit directly)
  php/{version}/
    etc/                # php-fpm pool configs
    var/log/            # php-fpm logs
  panel/logs/           # aapanel panel logs
  mysql/                # mysql data + logs

Nginx — Safe Change Pattern

Never edit files under vhost/ directly. aaPanel regenerates them on panel operations.

Instead, use includes:

# At the bottom of the vhost file (read-only reference):
# include /www/server/nginx/conf/custom/domain.com.conf;

# Create your changes here — aaPanel will not touch this:
# /www/server/nginx/conf/custom/domain.com.conf

Always verify before reload:

nginx -t && nginx -s reload

SSL — acme.sh

aaPanel uses acme.sh for cert management. List certs:

~/.acme.sh/acme.sh --list

Check expiry:

openssl x509 -enddate -noout -in /path/to/cert.pem

If taking ownership of a cert outside aaPanel, disable aaPanel's renewal cron for that domain to prevent conflicts.

Promtail — Log Scrape Config

Standard pipeline for this environment:

scrape_configs:
  - job_name: nginx
    static_configs:
      - targets: [localhost]
        labels:
          job: nginx
          server: __HOSTNAME__
          env: production
          __path__: /www/wwwlogs/*.log

  - job_name: php-fpm
    static_configs:
      - targets: [localhost]
        labels:
          job: php-fpm
          server: __HOSTNAME__
          env: production
          __path__: /www/server/php/*/var/log/*.log

  - job_name: aapanel
    static_configs:
      - targets: [localhost]
        labels:
          job: aapanel
          server: __HOSTNAME__
          env: production
          __path__: /www/server/panel/logs/*.log

Verify Promtail is shipping:

systemctl status promtail
curl -s localhost:9080/metrics | grep promtail_targets

Prometheus — Health Check

# All targets UP?
curl -s localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'

# Reload config without restart
curl -X POST localhost:9090/-/reload

Node.js — Pino Structured Logging

Apps must use pino, not console.log. Verify:

grep -r "console\.log" /www/wwwroot/app/src --include="*.js" --include="*.ts"

Pino log format expected by Promtail pipeline:

{"level":"info","time":1700000000000,"msg":"request handled","req":{"method":"GET","url":"/api/health"}}

Common Runbook

Nginx not reloading:

nginx -t                          # find syntax error
journalctl -u nginx --since "5m"  # check systemd logs

Promtail not shipping logs:

journalctl -u promtail --since "10m"
curl localhost:9080/ready
ls -la /www/wwwlogs/              # check file permissions

High PHP-FPM load:

ps aux | grep php-fpm
cat /www/server/php/*/etc/php-fpm.conf | grep max_children