ArticleReplaceBatch/docs/DEPLOYMENT_GUIDE.md

# 部署指南

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

---

## 目录

- [环境要求](#环境要求)
- [本地部署](#本地部署)
- [服务器部署](#服务器部署)
- [容器化部署](#容器化部署)
- [常见问题](#常见问题)

---

## 环境要求

### 系统要求

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

### 依赖要求

见 `requirements.txt` 文件。

---

## 本地部署

### 1. 获取代码

```bash
git clone <repository-url>
cd ArticleReplaceBatch
```

### 2. 创建虚拟环境

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置环境

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

### 5. 初始化配置

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

### 6. 运行应用

```bash
# GUI模式
python ArticleReplace.py

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

---

## 服务器部署

### 1. 安装系统依赖

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-pip
sudo apt install -y xvfb  # 无GUI运行需要
```

**CentOS/RHEL:**
```bash
sudo yum install -y python3 python3-venv python3-pip
sudo yum install -y xorg-x11-server-Xvfb
```

### 2. 创建部署目录

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

### 3. 部署应用

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

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

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

### 4. 配置环境

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

### 5. 创建服务文件

**创建 systemd 服务文件：**

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

**服务文件内容：**

```ini
[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. 启动服务

```bash
# 重新加载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

```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. 构建镜像

```bash
docker build -t article-replace:latest .
```

### 4. 运行容器

```bash
# 交互式运行
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:**

```yaml
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
```

**启动服务:**

```bash
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

---

## 监控和维护

### 日志管理

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

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

### 备份管理

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

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

### 性能监控

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

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

---

## 安全建议

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

---

## 常见问题

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

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

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

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

### Q: 如何处理依赖冲突？

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

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

### Q: 如何设置开机自启？

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

### Q: 内存不足怎么办？

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

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

---

## 升级指南

### 1. 备份数据

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

### 2. 获取新版本

```bash
git pull origin main
```

### 3. 更新依赖

```bash
pip install -r requirements.txt --upgrade
```

### 4. 验证升级

```bash
python dev.py test
```

### 5. 重启服务

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

---

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