🚀 Ledger 部署指南

本文档提供 Ledger 账本服务的完整部署指南，涵盖开发、测试和生产环境的部署方案。

🎯 部署架构

系统要求

组件	最低要求	推荐配置	说明
CPU	1 核心	2+ 核心	支持并发处理
内存	512MB	1GB+	包含数据库连接池
存储	1GB	10GB+	日志和数据存储
数据库	MySQL 5.7+	MySQL 8.0+	生产环境推荐

部署架构图

🐳 Docker 部署

单机部署

1. 构建镜像

# 克隆项目
git clone https://github.com/FixIterate/lz-stash.git
cd lz-stash

# 构建 Docker 镜像
docker build -t lzt:latest .

2. 准备配置文件

# config.yaml
server:
  port: 8080
  host: "0.0.0.0"

database:
  driver: mysql
  host: mysql
  port: 3306
  name: ledger_db
  user: ledger_user
  password: "your_password"
  max_connections: 10
  max_idle_connections: 5

logging:
  level: info
  format: json

3. Docker Compose 部署

# docker-compose.yml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: ledger_db
      MYSQL_USER: ledger_user
      MYSQL_PASSWORD: userpassword
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      timeout: 5s
      retries: 10

  ledger:
    image: lzt:latest
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_USER=ledger_user
      - DB_PASSWORD=userpassword
      - DB_NAME=ledger_db
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["./lzt", "ledger", "server", "--config", "/app/config.yaml"]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  mysql_data:

4. 启动服务

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f ledger

# 检查服务状态
docker-compose ps

☸️ Kubernetes 部署

生产环境部署

1. 配置文件 (ConfigMap)

# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: ledger-config
  namespace: default
data:
  config.yaml: |
    server:
      port: 8080
      host: "0.0.0.0"
    database:
      driver: mysql
      host: mysql-service
      port: 3306
      name: ledger_db
      user: ledger_user
      max_connections: 20
      max_idle_connections: 10
    logging:
      level: info
      format: json

2. 密钥管理 (Secret)

# k8s/secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: ledger-secret
  namespace: default
type: Opaque
data:
  db-password: <base64-encoded-password>
  db-root-password: <base64-encoded-root-password>

3. 服务部署 (Deployment)

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ledger-service
  namespace: default
  labels:
    app: ledger
spec:
  replicas: 3
  selector:
    matchLabels:
      app: ledger
  template:
    metadata:
      labels:
        app: ledger
    spec:
      containers:
      - name: ledger
        image: lzt:latest
        ports:
        - containerPort: 8080
        env:
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: ledger-secret
              key: db-password
        volumeMounts:
        - name: config-volume
          mountPath: /app/config.yaml
          subPath: config.yaml
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
      - name: config-volume
        configMap:
          name: ledger-config

4. 服务暴露 (Service)

# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: ledger-service
  namespace: default
spec:
  selector:
    app: ledger
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8080
  type: ClusterIP

5. 入口控制器 (Ingress)

# k8s/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ledger-ingress
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - api.yourcompany.com
    secretName: ledger-tls
  rules:
  - host: api.yourcompany.com
    http:
      paths:
      - path: /api/v1/ledger
        pathType: Prefix
        backend:
          service:
            name: ledger-service
            port:
              number: 80

部署命令

# 创建命名空间
kubectl create namespace ledger

# 应用配置
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml
kubectl apply -f k8s/ingress.yaml

# 检查部署状态
kubectl get pods -l app=ledger
kubectl get services
kubectl get ingress

🔧 环境配置

开发环境

# config/development.yaml
server:
  port: 8080
  debug: true

database:
  driver: sqlite
  name: "ledger_dev.db"
  
logging:
  level: debug
  format: text

测试环境

# config/testing.yaml
server:
  port: 8080
  
database:
  driver: mysql
  host: test-mysql
  port: 3306
  name: ledger_test
  user: test_user
  password: "test_password"
  
logging:
  level: info
  format: json

生产环境

# config/production.yaml
server:
  port: 8080
  read_timeout: 30s
  write_timeout: 30s
  
database:
  driver: mysql
  host: prod-mysql-cluster
  port: 3306
  name: ledger_prod
  user: prod_user
  # password 通过环境变量提供
  max_connections: 50
  max_idle_connections: 25
  connection_max_lifetime: 300s
  
logging:
  level: warn
  format: json
  
metrics:
  enabled: true
  port: 9090

📊 监控和健康检查

健康检查端点

// 服务健康检查
GET /health
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "v1.0.0",
  "database": "connected",
  "uptime": "2h15m30s"
}

// 就绪性检查
GET /ready
{
  "ready": true,
  "checks": {
    "database": "pass",
    "migrations": "pass"
  }
}

Prometheus 监控

# 在 Kubernetes 中启用 ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: ledger-monitor
spec:
  selector:
    matchLabels:
      app: ledger
  endpoints:
  - port: metrics
    interval: 30s
    path: /metrics

🔄 CI/CD 集成

GitHub Actions 部署

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    tags:
      - 'v*'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Build and push Docker image
      run: |
        docker build -t ghcr.io/FixIterate/lzt:${{ github.ref_name }} .
        docker push ghcr.io/FixIterate/lzt:${{ github.ref_name }}
    
    - name: Deploy to Kubernetes
      run: |
        kubectl set image deployment/ledger-service \
          ledger=ghcr.io/FixIterate/lzt:${{ github.ref_name }}
        kubectl rollout status deployment/ledger-service

🚨 故障排除

常见问题

1. 数据库连接失败

# 检查数据库连接
kubectl exec -it ledger-pod -- ./lzt ledger init --dry-run

# 查看数据库日志
kubectl logs mysql-pod

2. 服务启动失败

# 查看服务日志
kubectl logs -l app=ledger

# 检查配置文件
kubectl describe configmap ledger-config

3. 性能问题

# 查看资源使用情况
kubectl top pods -l app=ledger

# 查看服务指标
curl http://localhost:9090/metrics

日志分析

# 查看错误日志
kubectl logs -l app=ledger | grep ERROR

# 实时查看日志
kubectl logs -f -l app=ledger

📚 相关文档

• 系统架构 - 详细的系统架构设计
• API 文档 - 完整的 API 参考
• 运维监控 - 监控和告警配置

---

💡 部署建议: 生产环境部署前，建议先在测试环境验证所有配置和流程，确保系统的稳定性和可靠性。