scrapinghub-stack-scrapy 镜像文档

镜像概述和主要用途

scrapinghub-stack-scrapy 是一个包含最新 Scrapy 框架及更新依赖项的软件栈镜像，旨在为 Scrapy 爬虫开发和运行提供稳定、统一的环境。该镜像通过分支和标签管理，支持不同 Python 版本（2 和 3）及 Scrapy 版本的组合，确保用户可按需选择适配的运行环境。

核心功能和特性

• 多版本支持：通过分支管理不同 Python 版本（2 和 3）及 Scrapy 版本的组合，满足不同项目需求。
• 依赖更新：集成最新的 Scrapy 框架及相关依赖项，确保功能完整性和安全性。
• 版本化标签：采用严格的标签策略，提供稳定版本（带发布日期）、主版本及开发版本标识，便于版本选择和追溯。
• 环境一致性：统一的运行环境减少因依赖差异导致的“在我这里能运行”问题，适合团队协作和生产部署。

使用场景和适用范围

• Scrapy 爬虫开发：作为本地开发环境，提供一致的依赖配置。
• 爬虫测试与调试：快速搭建临时环境，验证不同 Scrapy/Python 版本下的爬虫兼容性。
• 生产部署：通过指定稳定标签（带发布日期），确保生产环境中爬虫运行的可靠性。
• 多版本项目维护：同时维护基于 Python 2 和 Python 3 的 Scrapy 项目时，可通过不同镜像标签快速切换环境。

版本与标签管理

分支说明

仓库通过分支维护不同 Python 版本和 Scrapy 版本的软件栈，分支命名规则为 branch-<scrapy版本>[-py3]，其中：

• 无 -py3 后缀：基于 Python 2 的分支
• 有 -py3 后缀：基于 Python 3 的分支

示例：

• branch-1.0：Python 2 + Scrapy 1.0
• branch-1.1：Python 2 + Scrapy 1.1
• branch-1.1-py3：Python 3 + Scrapy 1.1

标签规则

使用 Git 标签标记镜像版本，所有标签对应 Docker 镜像可在 Docker Hub 查看。标签类型及说明如下：

1. 主版本标签

格式：<scrapy版本>[-py3]
用于标识基于特定 Scrapy 版本和 Python 版本的主版本，无 -py3 后缀表示 Python 2。

示例：

• 1.0：Python 2 + Scrapy 1.0
• 1.1：Python 2 + Scrapy 1.1
• 1.1-py3：Python 3 + Scrapy 1.1

2. 带发布日期的稳定版本标签（推荐）

格式：<scrapy版本>[-py3]-<发布日期>
每个正式发布的稳定版本均带日期标识，强烈推荐使用此类标签，避免版本变更风险。

示例：

• 1.1-20160429：2016-04-29 发布的 Python 2 + Scrapy 1.1 版本
• 1.1-py3-20160804：2016-08-04 发布的 Python 3 + Scrapy 1.1 版本

3. Latest 标签（不推荐）

格式：<scrapy版本>[-py3]-latest
自动从对应分支构建（如 branch-1.1-py3 对应 1.1-py3-latest），反映分支最新变更，可能不稳定，禁止在生产环境使用。

示例：

• 1.0-latest（对应 branch-1.0）
• 1.1-py3-latest（对应 branch-1.1-py3）

4. 临时开发标签

格式：<scrapy版本>[-py3]-<特性名称>
用于开发和测试新功能，功能稳定后会被移除，不应依赖此类标签。

示例：1.1-py3-some-feature

使用方法

拉取镜像

从 Docker Hub 拉取指定版本的镜像，推荐使用带发布日期的稳定标签：

# 拉取 Python 3 + Scrapy 1.1 稳定版本（2016-08-04发布）
docker pull scrapinghub/scrapinghub-stack-scrapy:1.1-py3-20160804

运行容器

运行容器时，通常需挂载本地 Scrapy 项目目录，并执行爬虫命令。以下为基本示例：

# 假设本地项目目录为 ./my-scrapy-project，运行名为 myspider 的爬虫
docker run -v $(pwd)/my-scrapy-project:/app \
  scrapinghub/scrapinghub-stack-scrapy:1.1-py3-20160804 \
  scrapy crawl myspider -s LOG_LEVEL=INFO

说明：

• -v $(pwd)/my-scrapy-project:/app：将本地项目目录挂载到容器内 /app 路径
• scrapy crawl myspider：执行 Scrapy 爬虫命令，可添加额外参数（如 -s 设置配置）

Docker Compose 配置示例

对于复杂项目，可使用 docker-compose.yml 管理服务（如需数据库等依赖）：

version: '3'
services:
  scrapy:
    image: scrapinghub/scrapinghub-stack-scrapy:1.1-py3-20160804
    volumes:
      - ./my-scrapy-project:/app
    command: scrapy crawl myspider -s LOG_LEVEL=INFO
    # 如需网络或环境变量配置，可添加相应字段
    # environment:
    #   - PROXY_URL=[***]
    # network_mode: "host"

运行：docker-compose up

发布流程（维护者指南）

如需发布新版本镜像，需按以下步骤操作：

1. 拉取分支最新代码

确保本地分支为待发布分支，并拉取远程最新变更：

git pull origin <branch>
# 示例：拉取 Python 3 + Scrapy 1.1 分支
git pull origin branch-1.1-py3

2. 创建标签

根据版本规则创建标签，包括主版本标签和带日期的稳定版本标签（-latest 标签由分支自动构建，无需手动创建）：

# 创建主版本标签（如 1.1-py3）
git tag -f 1.1-py3
# 创建带日期的稳定版本标签（如 1.1-py3-20160804）
git tag 1.1-py3-20160804

3. 推送分支和标签

同时推送分支更新和标签，触发构建流程：

git push -f origin <branch> <tag1> <tag2>
# 示例：推送分支及两个标签
git push -f origin branch-1.1-py3 1.1-py3 1.1-py3-20160804

注意：需确保标签与分支更新同时推送，否则可能无法触发自动构建，需手动在构建平台重新触发。

4. 验证发布结果

检查标签是否在以下平台更新：

• GitHub 发布页：[***]
• Docker Hub 标签页：[***]

5. 功能一致性维护

除 Python 2/3 等不兼容场景外，新功能需同步更新到所有版本分支，确保各版本功能一致性。