opc-manager/deploy/README.md

# OPC-Manager 自动化部署指南

## 架构

```
开发者 push main → Gitea 仓库 (git.qiukai.me)
                        ↓
                  Gitea Actions 触发
                        ↓
            Runner（跑在业务服务器 82.157.208.197 上）
                        ↓
            git clone → rsync 到 release 目录
                        ↓
            创建 venv → pip install → systemctl restart
                        ↓
            健康检查 → 切换 current 软链 → 清理旧版本
```

## 服务器目录结构

```
/opt/opc-manager/
├── releases/
│   ├── abc1234/     ← 本次发布（commit sha）
│   ├── def5678/     ← 上次发布
│   └── ...          ← 保留最近 5 个
├── shared/
│   ├── .env         ← 环境变量（不进 git，持久化）
│   └── uploads/     ← 上传的文件（持久化，跨版本共享）
└── current → releases/abc1234  ← 软链，指向当前生效版本
```

## 一次性准备（在业务服务器上执行）

### 1. 安装 Gitea Actions Runner

```bash
# 下载 act_runner
cd /opt
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64 -O act_runner
chmod +x act_runner
mv act_runner /usr/local/bin/

# 注册 runner（到 git.qiukai.me）
# 先在 Gitea 网页：仓库设置 → Actions → Runners → New runner，获取 token
act_runner register \
  --instance https://git.qiukai.me \
  --token <YOUR_RUNNER_TOKEN> \
  --name prod-deploy \
  --labels prod-deploy \
  --no-interactive

# 安装为系统服务
act_runner daemon --config /etc/act_runner/config.yaml &
# 或用 systemd：
cat > /etc/systemd/system/act-runner.service <<'EOF'
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/act_runner daemon
Restart=on-failure
Environment=HOME=/root

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now act-runner
```

### 2. 创建部署目录结构

```bash
mkdir -p /opt/opc-manager/{releases,shared/uploads}
```

### 3. 创建 .env 文件

```bash
cat > /opt/opc-manager/shared/.env <<'EOF'
SECRET_KEY=改成一串随机字符串_至少32位
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=opc
DB_PASSWORD=opc123456
DB_NAME=opc
FLASK_DEBUG=false
EOF

chmod 600 /opt/opc-manager/shared/.env
```

### 4. 安装 systemd service

```bash
# 从仓库的 deploy/opc-manager.service 复制
cat > /etc/systemd/system/opc-manager.service <<'EOF'
[Unit]
Description=OPC Manager (Flask)
After=network.target mysql.service

[Service]
Type=simple
WorkingDirectory=/opt/opc-manager/current
ExecStart=/opt/opc-manager/current/.venv/bin/gunicorn --preload -w 4 -b 0.0.0.0:5177 backend.flask_app:app
Restart=on-failure
RestartSec=5
EnvironmentFile=/opt/opc-manager/current/.env

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable opc-manager
```

### 5. 配置 Gitea Secret

在 Gitea 网页操作：
1. 进入仓库 `qiukai/opc-manager`
2. 设置 → Actions → Secrets → New Secret
3. Name: `DEPLOY_TOKEN`
4. Value: 你的 Gitea Personal Access Token（需要有 repo 读权限）
   - 生成路径：头像 → 设置 → 应用 → 生成令牌

### 6. 首次手动部署

push 代码前，先手动跑一次确保目录结构正确：

```bash
cd /opt/opc-manager
git clone --depth 1 --branch main https://git.qiukai.me/qiukai/opc-manager.git /tmp/opc-init
RELEASE_DIR=/opt/opc-manager/releases/initial
mkdir -p "${RELEASE_DIR}"
rsync -a --exclude='.git' --exclude='.env' --exclude='.venv' /tmp/opc-init/ "${RELEASE_DIR}/"
ln -sfn /opt/opc-manager/shared/.env "${RELEASE_DIR}/.env"
ln -sfn /opt/opc-manager/shared/uploads "${RELEASE_DIR}/data/uploads"
cd "${RELEASE_DIR}"
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
ln -sfn "${RELEASE_DIR}" /opt/opc-manager/current
systemctl start opc-manager
curl http://127.0.0.1:5177/api/health
rm -rf /tmp/opc-init
```

## 日常使用

### 发布新版本
```bash
# 本地
git push origin main
# 自动触发 Gitea Actions → 服务器自动部署
```

### 查看部署状态
```bash
# 在 Gitea 网页：仓库 → Actions 查看部署日志
# 或在服务器：
systemctl status opc-manager
ls -la /opt/opc-manager/current
```

### 回滚
```bash
# 列出历史版本
ls -t /opt/opc-manager/releases
# 切换到上一个版本
PREV=$(ls -t /opt/opc-manager/releases | sed -n '2p')
ln -sfn "/opt/opc-manager/releases/${PREV}" /opt/opc-manager/current
systemctl restart opc-manager
```

## Nginx 反代（可选）

```nginx
server {
    listen 80;
    server_name opc.yxcowork.vip;
    location / {
        proxy_pass http://127.0.0.1:5177;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```