1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# GCC / Clang
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DHICAL_BUILD_TESTS=OFF \
      -DHICAL_BUILD_EXAMPLES=OFF

cmake --build build -j$(nproc)

# MSVC
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# GCC — ThinLTO 速度更快，Fat LTO 优化更激进
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON

# Clang — 推荐 ThinLTO（并行链接）
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_FLAGS="-flto=thin" \
      -DCMAKE_EXE_LINKER_FLAGS="-flto=thin -fuse-ld=lld"

# MSVC — /GL + /LTCG
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_FLAGS="/GL" \
      -DCMAKE_EXE_LINKER_FLAGS="/LTCG"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 第一步：构建 instrumented 版本
cmake -B build-pgo1 -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_FLAGS="-fprofile-generate=/tmp/pgo-data"
cmake --build build-pgo1 -j$(nproc)

# 第二步：用真实流量跑 profile（至少跑 30 秒覆盖主要路径）
./build-pgo1/your_server &
wrk -t4 -c100 -d30s http://127.0.0.1:8080/api/status
wrk -t4 -c100 -d30s -s post.lua http://127.0.0.1:8080/api/echo
kill %1

# 第三步：基于 profile 重新编译
cmake -B build-pgo2 -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_FLAGS="-fprofile-use=/tmp/pgo-data -fprofile-correction"
cmake --build build-pgo2 -j$(nproc)

1
2
3
4
5
6
7
8

# 全静态链接（GCC + musl，需要 Alpine 或 musl-cross 工具链）
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_EXE_LINKER_FLAGS="-static" \
      -DBUILD_SHARED_LIBS=OFF

# Boost 静态链接（默认行为，Hical vcpkg/Conan 配置均输出静态库）
cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DBoost_USE_STATIC_LIBS=ON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# /etc/systemd/system/hical-app.service
[Unit]
Description=Hical Web Application
After=network.target mysql.service
Wants=mysql.service

[Service]
Type=simple
User=hical
Group=hical
WorkingDirectory=/opt/hical
ExecStart=/opt/hical/server 8080
ExecReload=/bin/kill -HUP $MAINPID

# 优雅关机：先 SIGTERM，等 35 秒（比 Hical 默认 30 秒 shutdown timeout 多 5 秒）
KillSignal=SIGTERM
TimeoutStopSec=35

# 自动重启（非正常退出时）
Restart=on-failure
RestartSec=3

# 资源限制
LimitNOFILE=65536
LimitCORE=infinity
MemoryMax=2G

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/hical/logs /opt/hical/data

# 环境变量
Environment=MYSQL_HOST=127.0.0.1
Environment=MYSQL_PORT=3306
EnvironmentFile=-/opt/hical/.env

[Install]
WantedBy=multi-user.target

1
2
3
4
5
6
7
8

# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable hical-app
sudo systemctl start hical-app

# 查看状态
sudo systemctl status hical-app
sudo journalctl -u hical-app -f    # 实时日志

1
2
3

// HttpServer 内部已注册：
// SIGINT  (Ctrl+C) → gracefulStop()
// SIGTERM (kill)   → gracefulStop()

1
2
3

HttpServer server(8080, 4);
server.setShutdownTimeout(45.0);  // 45 秒后强制关闭
server.start();

1
2
3
4
5

// 推荐：直接设置 ioThreads = CPU 核数
// 框架自动在 Linux/macOS 上启用 SO_REUSEPORT 多 acceptor
// Windows 自动回退为单 acceptor（多 worker loop 仍然有效）
HttpServer server(8080, std::thread::hardware_concurrency());
server.start();

1
2
3
4

# 多进程 + SO_REUSEPORT（极端场景，通常不需要）
for i in $(seq 1 $(nproc)); do
    /opt/hical/server 8080 &
done

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# /etc/nginx/conf.d/hical-app.conf

upstream hical_backend {
    # 多实例负载均衡
    server 127.0.0.1:8080;
    # server 127.0.0.1:8081;  # 如果有多进程
    
    keepalive 64;              # 长连接复用，减少 TCP 握手
}

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    # SSL 证书（Let's Encrypt）
    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1h;

    # 安全头
    add_header X-Frame-Options DENY always;
    add_header X-Content-Type-Options nosniff always;
    add_header Strict-Transport-Security "max-age=63072000" always;

    # 请求体限制（与 Hical setMaxBodySize 保持一致或略大）
    client_max_body_size 10m;

    # 限流（每 IP 每秒 50 请求，突发允许 100）
    limit_req_zone $binary_remote_addr zone=api:10m rate=50r/s;

    # API 路由
    location /api/ {
        limit_req zone=api burst=100 nodelay;
        
        proxy_pass http://hical_backend;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";    # 启用 keepalive
        
        # 超时配置
        proxy_connect_timeout 5s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # 静态文件直接由 Nginx 处理
    location /static/ {
        root /opt/hical/public;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 在 server 块中添加
location /ws/ {
    proxy_pass http://hical_backend;
    proxy_http_version 1.1;
    
    # WebSocket 升级必需
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    
    # WebSocket 长连接，超时要设长一些
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

1
2
3

// Hical 不需要 enableSsl()，直接监听明文
HttpServer server(8080, 4);
server.start();

1
2
3

HttpServer server(8080, 4);
server.enableSsl("/path/to/cert.pem", "/path/to/key.pem");
server.start();

1
2
3
4
5
6

# Nginx 侧配置 proxy_pass 为 https
location /api/ {
    proxy_pass https://hical_backend;
    proxy_ssl_verify off;            # 内网自签证书可关闭验证
    proxy_ssl_server_name on;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

#include "core/HttpServer.h"
#include <atomic>
#include <chrono>
#include <mutex>
#include <unordered_map>

using namespace hical;

// 简易指标收集器
struct Metrics
{
    std::atomic<uint64_t> totalRequests {0};
    std::atomic<uint64_t> totalErrors {0};       // 5xx
    std::atomic<uint64_t> activeConnections {0};
    
    // 按路径统计（需要锁）
    struct PathStats
    {
        uint64_t count = 0;
        double totalLatencyMs = 0;
    };
    std::mutex mtx;
    std::unordered_map<std::string, PathStats> pathStats;
    
    void record(const std::string& path, double latencyMs, int status)
    {
        totalRequests.fetch_add(1, std::memory_order_relaxed);
        if (status >= 500)
        {
            totalErrors.fetch_add(1, std::memory_order_relaxed);
        }
        std::lock_guard lock(mtx);
        auto& s = pathStats[path];
        s.count++;
        s.totalLatencyMs += latencyMs;
    }
    
    std::string toPrometheus() const
    {
        std::string out;
        out += "# HELP http_requests_total Total HTTP requests\n";
        out += "# TYPE http_requests_total counter\n";
        out += "http_requests_total " + std::to_string(totalRequests.load()) + "\n";
        out += "# HELP http_errors_total Total HTTP 5xx errors\n";
        out += "# TYPE http_errors_total counter\n";
        out += "http_errors_total " + std::to_string(totalErrors.load()) + "\n";
        out += "# HELP http_active_connections Current active connections\n";
        out += "# TYPE http_active_connections gauge\n";
        out += "http_active_connections " + std::to_string(activeConnections.load()) + "\n";
        return out;
    }
};

Metrics g_metrics;

int main()
{
    HttpServer server(8080, 4);
    
    // 指标收集中间件
    server.use(
        [](HttpRequest& req, MiddlewareNext next) -> Awaitable<HttpResponse>
        {
            g_metrics.activeConnections.fetch_add(1, std::memory_order_relaxed);
            auto start = std::chrono::steady_clock::now();
            
            auto res = co_await next(req);
            
            auto elapsed = std::chrono::steady_clock::now() - start;
            double ms = std::chrono::duration<double, std::milli>(elapsed).count();
            g_metrics.record(std::string(req.path()), ms, static_cast<int>(res.statusCode()));
            g_metrics.activeConnections.fetch_sub(1, std::memory_order_relaxed);
            
            co_return res;
        });
    
    // Prometheus 拉取端点
    server.router().get("/metrics",
                        [](const HttpRequest&) -> HttpResponse
                        {
                            auto body = g_metrics.toPrometheus();
                            auto res = HttpResponse::ok(std::move(body));
                            res.setHeader("Content-Type", "text/plain; version=0.0.4");
                            return res;
                        });
    
    server.start();
}

1
2
3
4
5
6

scrape_configs:
  - job_name: 'hical-app'
    scrape_interval: 15s
    static_configs:
      - targets: ['hical-server:8080']
    metrics_path: '/metrics'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

#include "core/Log.h"
#include "core/LogFormatter.h"
#include "core/AsyncFileSink.h"

using namespace hical;

void setupProductionLogging()
{
    auto& logger = Logger::instance();
    logger.setLevel(LogLevel::hInfo);    // 生产环境不要 Debug/Trace
    
    // JSON 格式化器 — 输出 JSON Lines，一行一条日志
    logger.setFormatter(std::make_shared<JsonFormatter>());
    
    // 异步文件 Sink — 双缓冲，不阻塞业务线程
    AsyncFileSink::Options opts;
    opts.file.basePath = "/var/log/hical/app.log";
    opts.file.maxFileSize = 100 * 1024 * 1024;       // 100MB 轮转
    opts.file.maxFiles = 10;                          // 保留 10 个归档
    opts.bufferSize = 4 * 1024 * 1024;                // 4MB 双缓冲
    opts.backpressureLimit = 8 * 1024 * 1024;         // 背压阈值，超出后丢弃 + 计数
    opts.flushInterval = std::chrono::milliseconds(1000);  // 1s 定时刷盘
    
    logger.addSink(std::make_shared<AsyncFileSink>(opts));
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
    "timestamp": "2026-05-08T10:30:45.123Z",
    "level": "INFO",
    "threadId": 14235,
    "file": "HttpServer.cpp",
    "line": 145,
    "message": "Server started on port 8080",
    "traceId": "a1b2c3d4e5f6...",
    "fields": {
        "port": 8080,
        "threads": 4
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

filebeat.inputs:
  - type: log
    paths:
      - /var/log/hical/app*.log
    json.keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["elasticsearch:9200"]
  index: "hical-%{+yyyy.MM.dd}"

1
2
3
4
5
6
7
8
9

void setupContainerLogging()
{
    auto& logger = Logger::instance();
    logger.setLevel(LogLevel::hInfo);
    
    // 容器里直接用 stderr，JSON 格式（Formatter 设置在 Logger 上，而非 Sink）
    logger.setFormatter(std::make_shared<JsonFormatter>());
    logger.addSink(std::make_shared<StderrSink>());
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# docker-compose.yml 中配置 Loki 日志驱动
services:
  hical:
    image: hical-app:latest
    logging:
      driver: loki
      options:
        loki-url: "http://loki:3100/loki/api/v1/push"
        loki-batch-size: "400"
        labels: "app=hical,env=prod"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// 简单的存活检查
server.router().get("/health",
                    [](const HttpRequest&) -> HttpResponse
                    {
                        return HttpResponse::json({{"status", "ok"}});
                    });

// 深度检查（含数据库连通性）
server.router().get("/health/ready",
                    [&pool](const HttpRequest& req) -> Awaitable<HttpResponse>
                    {
                        try
                        {
                            auto conn = co_await pool.acquire();
                            co_await conn->ping();
                            pool.release(std::move(conn));
                            co_return HttpResponse::json({
                                {"status", "ok"},
                                {"db", "connected"}
                            });
                        }
                        catch (...)
                        {
                            auto res = HttpResponse::json({
                                {"status", "degraded"},
                                {"db", "disconnected"}
                            });
                            res.setStatus(HttpStatusCode::hServiceUnavailable);
                            co_return res;
                        }
                    });

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# ============ 构建阶段 ============
FROM ubuntu:24.04 AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    cmake make g++ python3 python3-pip pipx ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Conan 2 包管理器
RUN pipx install conan && pipx ensurepath
ENV PATH="/root/.local/bin:${PATH}"
RUN conan profile detect

WORKDIR /src
COPY conanfile.py CMakeLists.txt ./
COPY src/ src/

# 分离依赖安装（利用 Docker 缓存层）
RUN conan install . --build=missing -s build_type=Release -s compiler.cppstd=20

# 复制应用代码（放在依赖安装之后，应用代码变化不会重新安装依赖）
COPY . .

# 编译
RUN cmake --preset conan-release \
    -DHICAL_BUILD_TESTS=OFF \
    -DHICAL_BUILD_EXAMPLES=OFF \
    -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON \
    && cmake --build --preset conan-release -j$(nproc)

# ============ 运行阶段 ============
FROM ubuntu:24.04

# 仅安装运行时依赖
RUN apt-get update && apt-get install -y --no-install-recommends \
    libssl3 ca-certificates \
    && rm -rf /var/lib/apt/lists/* \
    && groupadd -r hical && useradd -r -g hical hical

COPY --from=builder /src/build/Release/your_server /app/server

# 非 root 运行
USER hical
WORKDIR /app

EXPOSE 8080

# 健康检查
HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
    CMD curl -f http://localhost:8080/health || exit 1

CMD ["/app/server"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# docker-compose.prod.yml
services:
  # ---- Hical 应用 ----
  hical:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      - MYSQL_HOST=mysql
      - MYSQL_PORT=3306
      - MYSQL_USER=hical
      - MYSQL_PASSWORD_FILE=/run/secrets/db_password
      - MYSQL_DATABASE=hical_prod
    secrets:
      - db_password
    expose:
      - "8080"                    # 仅内部网络可访问
    deploy:
      resources:
        limits:
          cpus: "4"
          memory: 1G
        reservations:
          cpus: "1"
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 3
    networks:
      - backend
    depends_on:
      mysql:
        condition: service_healthy

  # ---- MySQL ----
  mysql:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_root_password
      - MYSQL_DATABASE=hical_prod
      - MYSQL_USER=hical
      - MYSQL_PASSWORD_FILE=/run/secrets/db_password
    secrets:
      - db_root_password
      - db_password
    volumes:
      - mysql_data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 1G
    networks:
      - backend

  # ---- Nginx 反向代理 ----
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./static:/usr/share/nginx/html/static:ro
    depends_on:
      - hical
    networks:
      - frontend
      - backend

secrets:
  db_password:
    file: ./secrets/db_password.txt
  db_root_password:
    file: ./secrets/db_root_password.txt

volumes:
  mysql_data:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true              # 后端网络不可直接从外部访问

1
2
3
4
5
6
7
8

# 构建并启动
docker compose -f docker-compose.prod.yml up -d --build

# 查看日志
docker compose -f docker-compose.prod.yml logs -f hical

# 滚动更新（零停机，需要多副本）
docker compose -f docker-compose.prod.yml up -d --no-deps --build hical

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# hical-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hical-app
  labels:
    app: hical
spec:
  replicas: 3
  selector:
    matchLabels:
      app: hical
  template:
    metadata:
      labels:
        app: hical
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8080"
        prometheus.io/path: "/metrics"
    spec:
      containers:
        - name: hical
          image: registry.example.com/hical-app:latest
          ports:
            - containerPort: 8080
          env:
            - name: MYSQL_HOST
              value: "mysql-service"
            - name: MYSQL_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: hical-db-secret
                  key: password
          resources:
            requests:
              cpu: "500m"
              memory: "256Mi"
            limits:
              cpu: "2"
              memory: "1Gi"
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: hical-service
spec:
  selector:
    app: hical
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: hical-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hical-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

1
2
3
4
5
6
7
8

1. 先用默认参数跑压测，记录基线 QPS / P99 延迟 / 内存
2. 逐个调整单一参数，对比压测结果
3. 优先调线程数 → 连接池 → 内存池（边际收益递减）
4. 用 perf top / flamegraph 定位 CPU 热点
5. 用 /metrics 端点观察运行时指标
6. 用 LogAdmin 端点运行时调整日志级别（无需重启）
   GET  /admin/log-level          # 查看当前级别
   PUT  /admin/log-level          # 动态调整