sourcepole/qwc-uwsgi-base

QWC uwsgi 基础镜像文档

1. 镜像概述和主要用途

QWC uwsgi 基础镜像是 QWC 服务生态的基础组件之一，基于 uWSGI 服务器构建，主要用于支持 Python Web 应用的部署与运行。该镜像提供了标准的 WSGI 协议实现，作为 QWC 系列服务的底层运行环境，可帮助开发者快速构建和部署基于 Python 的 Web 服务。

核心定位：作为 QWC 服务（如 qwc-odk-service、qwc-mapviewer 等）的基础镜像，提供统一的 uWSGI 运行环境，简化上层应用的容器化构建流程。

2. 核心功能和特性

2.1 uWSGI 核心能力

• 支持 WSGI 1.0/2.0 协议，兼容主流 Python Web 框架（如 Flask、Django）
• 多进程/多线程运行模式，可通过配置灵活调整资源占用
• 内置请求路由、负载均衡和连接池管理
• 支持 HTTP/HTTPS 协议（需配合插件）及 Unix Socket 通信

2.2 基础镜像特性

• 精简的基础环境，基于 Alpine 或 Debian（具体取决于构建版本），减小镜像体积
• 预配置基础 uWSGI 参数，降低上层应用配置复杂度
• 标准化的日志输出格式，便于集成日志收集系统
• 支持环境变量动态配置，无需修改配置文件即可调整运行参数
• 可扩展性强，允许通过 Dockerfile 继承并添加应用依赖

3. 使用场景和适用范围

3.1 典型使用场景

• 作为 QWC 系列服务（如数据服务、地图服务）的底层运行镜像
• 开发/测试环境中快速部署 Python Web 应用原型
• 生产环境中运行基于 WSGI 协议的 Python Web 服务

3.2 适用范围

• 基于 Python 开发的 Web 应用（需符合 WSGI 规范）
• QWC 服务生态的二次开发或自定义服务构建
• 需要统一 uWSGI 运行环境的多服务部署场景

4. 使用方法和配置说明

4.1 基础使用方式

该镜像作为基础镜像，通常需通过 Dockerfile 继承并添加应用代码及依赖。

4.1.1 Dockerfile 示例（构建上层应用镜像）

dockerfile
# 继承 QWC uwsgi 基础镜像
FROM qwc-uwsgi-base:latest

# 设置工作目录
WORKDIR /app

# 复制应用代码
COPY . /app

# 安装应用依赖（如需）
RUN pip install --no-cache-dir -r requirements.txt

# （可选）覆盖基础镜像的 uWSGI 配置
COPY uwsgi.ini /etc/uwsgi/

4.1.2 直接运行（测试场景）

通过挂载本地应用代码并指定 uWSGI 配置，可直接运行应用：

bash
docker run -d \
  --name qwc-app-test \
  -p 8000:8000 \
  -v $(pwd)/app:/app \
  -v $(pwd)/uwsgi.ini:/etc/uwsgi/uwsgi.ini \
  qwc-uwsgi-base:latest

4.1.3 docker-compose 配置示例

yaml
version: '3.8'

services:
  qwc-app:
    image: qwc-uwsgi-base:latest
    container_name: qwc-app
    restart: always
    ports:
      - "8000:8000"
    volumes:
      - ./app:/app  # 挂载应用代码目录
      - ./uwsgi.ini:/etc/uwsgi/uwsgi.ini  # 挂载自定义配置文件（可选）
    environment:
      - UWSGI_WORKERS=4  # 工作进程数
      - UWSGI_THREADS=2  # 每个进程的线程数
      - UWSGI_MODULE=wsgi:app  # 应用入口模块（格式：<模块名>:<可调用对象>）
      - LOG_LEVEL=info  # 日志级别

4.2 环境变量配置

通过环境变量可动态调整 uWSGI 运行参数，无需修改配置文件。常用参数如下：

4.3 uWSGI 配置文件说明

如需更复杂的配置（如 SSL、超时设置、静态文件映射），可通过挂载自定义 uwsgi.ini 文件实现。基础配置示例：

ini
# uwsgi.ini 示例
[uwsgi]
http = :$(UWSGI_PORT)
module = $(UWSGI_MODULE)
callable = $(UWSGI_CALLABLE)
workers = $(UWSGI_WORKERS)
threads = $(UWSGI_THREADS)
master = $(UWSGI_MASTER)
listen = $(UWSGI_LISTEN)
logto = /var/log/uwsgi.log
log-reopen = true  # 日志轮转支持

5. 注意事项

• 该镜像为基础组件，需配合具体应用代码使用，不可单独作为服务运行
• 生产环境中建议通过环境变量或配置文件限制资源使用（如 workers 数量需根据宿主机 CPU 核心数调整）
• 更多细节及最新版本信息请参考官方仓库：https://github.com/qwc-services/qwc-docker
• 应用依赖需在继承镜像的 Dockerfile 中通过 pip install 或 apk add 等命令添加