timescaledev/timescaledb-ha

通用环境兼容镜像

镜像概述和主要用途

本镜像为跨环境通用型容器化解决方案，设计目标是同时支持在Kubernetes（K8s）集群环境和非K8s环境（如独立Docker引擎、Docker Compose等）中运行。通过统一的容器封装，提供一致的应用部署体验，减少因基础设施差异导致的适配成本，适用于需要在多样化环境中灵活部署的服务或工具类应用。

核心功能和特性

• 环境无关性：无需修改镜像即可在K8s集群（通过Pod调度）和非K8s环境（独立Docker运行）中启动，实现"一次构建，多环境运行"。
• 轻量级架构：基于精简基础镜像构建，降低镜像体积和运行时资源占用，提升启动效率。
• 配置灵活性：支持通过环境变量、命令行参数及外部配置文件进行定制，适配不同场景需求。
• 跨平台支持：兼容常见CPU架构（如amd64、arm64），可部署于物理机、虚拟机、云服务器等多种硬件环境。

使用场景和适用范围

K8s环境

• 作为微服务组件部署于K8s集群，通过Deployment/StatefulSet实现高可用调度
• 集成K8s原生功能（ConfigMap/Secret配置管理、Service暴露、Ingress路由）
• 在K8s Job/CronJob中作为任务型应用执行一次性或周期性任务

非K8s环境

• 开发/测试环境：本地Docker引擎中快速启动，验证应用功能
• 单机部署：边缘设备或小型服务器上通过独立Docker运行
• 多实例协同：通过Docker Compose编排实现服务组合部署

混合环境

• 多云架构：同时部署于私有K8s集群和公有云容器服务
• 过渡场景：从独立Docker环境平滑迁移至K8s集群

使用方法和配置说明

前提条件

• Docker引擎20.10+ 或 K8s集群1.21+
• 网络可访问镜像仓库（如Docker Hub、私有仓库）

镜像拉取

bash
docker pull [镜像仓库地址]/[镜像名称]:[版本标签]

提示：生产环境建议使用固定版本标签（如v1.0.0）而非latest，确保部署一致性

非K8s环境部署

基础运行命令（Docker）

bash
docker run -d \
  --name app-instance \
  -p 8080:8080 \  # 端口映射（主机端口:容器端口）
  -v /host/data:/app/data \  # 数据卷挂载（持久化存储）
  -e APP_ENV=production \  # 环境变量：运行环境标识
  -e LOG_LEVEL=info \  # 环境变量：日志级别
  --restart unless-stopped \  # 自动重启策略
  [镜像仓库地址]/[镜像名称]:[版本标签]

Docker Compose配置示例

yaml
# docker-compose.yml
version: '3.8'
services:
  app:
    image: [镜像仓库地址]/[镜像名称]:[版本标签]
    container_name: app-service
    ports:
      - "8080:8080"
    volumes:
      - app-data:/app/data  # 命名卷（自动创建）
      - ./config:/app/config  # 绑定挂载本地配置目录
    environment:
      - APP_ENV=production
      - LOG_LEVEL=info
      - MAX_CONCURRENT=10  # 并发连接限制（示例参数）
    restart: unless-stopped

volumes:
  app-data:  # 声明命名卷，数据持久化独立于容器生命周期

启动服务：docker-compose up -d

K8s环境部署

Deployment配置示例

yaml
# app-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-deployment
  namespace: default
spec:
  replicas: 3  # 3个副本确保高可用
  selector:
    matchLabels:
      app: demo-app
  template:
    metadata:
      labels:
        app: demo-app
    spec:
      containers:
      - name: app-container
        image: [镜像仓库地址]/[镜像名称]:[版本标签]
        ports:
        - containerPort: 8080
        env:
        - name: APP_ENV
          value: "production"
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: log_level  # 从ConfigMap读取配置
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "256Mi"
        volumeMounts:
        - name: app-data
          mountPath: /app/data
      volumes:
      - name: app-data
        persistentVolumeClaim:
          claimName: app-pvc  # 引用预创建的PVC

部署命令：kubectl apply -f app-deployment.yaml

配置参数说明

环境变量

命令行参数

通过镜像入口命令传递，格式：docker run [镜像] [参数]

• --help：查看帮助信息
• --version：显示版本号
• --config <path>：指定配置文件路径（覆盖CONFIG_PATH环境变量）

注意事项

1. 数据持久化：生产环境必须挂载数据卷，避免容器重建导致数据丢失
2. 资源限制：K8s环境建议配置resources限制，非K8s环境可通过--memory/--cpus参数限制资源
3. 安全加固：
   • 使用非root用户运行容器（通过USER指令或K8s securityContext）
   • 敏感配置通过Secret管理（K8s）或加密环境变量（Docker）
4. 版本管理：建立镜像版本控制策略，避免直接使用latest标签

故障排查

• 启动失败：检查日志 docker logs <容器ID> 或 kubectl logs <pod名称>，重点排查配置错误、端口冲突
• 资源不足：K8s环境中Pod状态为Pending时，检查节点资源是否充足或调整resources.requests
• 数据卷权限：挂载宿主目录时确保容器内用户有读写权限（可通过chmod调整宿主目录权限）
• 网络问题：确认端口映射正确，防火墙规则允许流量通过，K8s环境检查Service和Ingress配置