ArticleReplaceBatch/docs/DEPLOYMENT_GUIDE.md

部署指南

本文档提供了ArticleReplaceBatch项目的部署指南。

---

目录

• 环境要求
• 本地部署
• 服务器部署
• 容器化部署
• 常见问题

---

环境要求

系统要求

• 操作系统: Windows 10+, Linux (Ubuntu 20.04+), macOS 10.15+
• Python版本: 3.10 或更高版本
• 内存: 最低 2GB，推荐 4GB+
• 磁盘空间: 最低 1GB

依赖要求

见 requirements.txt 文件。

---

本地部署

1. 获取代码

git clone <repository-url>
cd ArticleReplaceBatch

2. 创建虚拟环境

python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 配置环境

cp .env.example .env
# 编辑 .env 文件，填写必要的配置

5. 初始化配置

python -c "from config import CONFIG; print('配置初始化完成')"

6. 运行应用

# GUI模式
python ArticleReplace.py

# 命令行模式
python cli.py --help

---

服务器部署

1. 安装系统依赖

Ubuntu/Debian:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip
sudo apt install -y xvfb  # 无GUI运行需要

CentOS/RHEL:

sudo yum install -y python3 python3-venv python3-pip
sudo yum install -y xorg-x11-server-Xvfb

2. 创建部署目录

sudo mkdir -p /opt/article-replace
sudo chown $USER:$USER /opt/article-replace
cd /opt/article-replace

3. 部署应用

# 复制代码到部署目录
git clone <repository-url> .
git checkout main

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

4. 配置环境

cp .env.example .env
# 编辑 .env 文件
nano .env

5. 创建服务文件

创建 systemd 服务文件：

sudo nano /etc/systemd/system/article-replace.service

服务文件内容：

[Unit]
Description=Article Replace Batch Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/article-replace
Environment="PATH=/opt/article-replace/venv/bin"
ExecStart=/opt/article-replace/venv/bin/python cli.py --excel /path/to/articles.xlsx --threads 3
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

6. 启动服务

# 重新加载systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start article-replace

# 设置开机自启
sudo systemctl enable article-replace

# 查看状态
sudo systemctl status article-replace

# 查看日志
sudo journalctl -u article-replace -f

---

容器化部署

1. 创建 Dockerfile

FROM python:3.11-slim

# 设置工作目录
WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    xvfb \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 创建必要目录
RUN mkdir -p logs backups articles picture

# 暴露端口（如果需要）
# EXPOSE 8000

# 设置环境变量
ENV PYTHONUNBUFFERED=1

# 默认命令
CMD ["python", "cli.py", "--help"]

2. 创建 .dockerignore

.git
.gitignore
__pycache__
*.pyc
*.pyo
*.pyd
venv
.env
logs/
backups/
archive/
build/
dist/
*.spec
.DS_Store

3. 构建镜像

docker build -t article-replace:latest .

4. 运行容器

# 交互式运行
docker run -it --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  article-replace:latest \
  python cli.py --excel /app/data/articles.xlsx --threads 3

# 后台运行
docker run -d \
  --name article-replace \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  article-replace:latest \
  python cli.py --excel /app/data/articles.xlsx --threads 3

# 查看日志
docker logs -f article-replace

5. 使用 Docker Compose

创建 docker-compose.yml:

version: '3.8'

services:
  article-replace:
    build: .
    container_name: article-replace
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - ./config:/app/config
    environment:
      - PYTHONUNBUFFERED=1
    command: python cli.py --excel /app/data/articles.xlsx --threads 3
    restart: unless-stopped

启动服务:

docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

---

监控和维护

日志管理

# 查看应用日志
tail -f logs/article_replace.log

# 清理旧日志
find logs/ -name "*.log" -mtime +7 -delete

备份管理

# 备份配置
cp config.ini backups/config_$(date +%Y%m%d).ini

# 备份数据
tar -czf backups/data_$(date +%Y%m%d).tar.gz articles/ picture/

性能监控

# 查看进程状态
ps aux | grep ArticleReplace

# 查看内存使用
top -p $(pgrep -f ArticleReplace)

---

安全建议

1. 环境变量: 不要将敏感信息提交到版本控制系统
2. 文件权限: 确保 .env 文件权限设置为 600
3. 防火墙: 如果暴露端口，配置防火墙规则
4. 更新: 定期更新依赖包以修复安全漏洞

---

常见问题

Q: 无GUI环境下如何运行？

A: 使用命令行模式或 xvfb。

# 使用命令行模式
python cli.py --excel articles.xlsx --threads 3

# 或使用 xvfb (Linux)
xvfb-run -a python ArticleReplace.py

Q: 如何处理依赖冲突？

A: 使用虚拟环境隔离依赖。

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Q: 如何设置开机自启？

A: 使用 systemd 服务（Linux）或任务计划程序（Windows）。

Q: 内存不足怎么办？

A: 增加系统内存或减少并发线程数。

# 减少线程数
python cli.py --excel articles.xlsx --threads 1

---

升级指南

1. 备份数据

# 备份配置和数据
cp config.ini backups/
tar -czf backups/data_backup_$(date +%Y%m%d).tar.gz articles/ picture/

2. 获取新版本

git pull origin main

3. 更新依赖

pip install -r requirements.txt --upgrade

4. 验证升级

python dev.py test

5. 重启服务

sudo systemctl restart article-replace
# 或
docker-compose restart

---

文档版本: v1.0
最后更新: 2026-03-07
维护者: opencode