egg/TEMP_spec_system_V3

Fork 0

Files

beabigegg dcd15baf3f 4TH

2025-08-28 13:20:29 +08:00

14 KiB

Raw Permalink Blame History

部署指南 - 暫時規範管理系統 V3

本文件提供詳細的部署指導，涵蓋不同平台和環境的部署方式。

📋 目錄

快速開始
平台特定部署
Docker 部署
生產環境部署
疑難排解

1. 快速開始

前置需求檢查清單

Python 3.8+ 已安裝
Docker 已安裝且運行中 (如使用 Docker 部署)
MySQL 8.0+ 或相容的資料庫
ONLYOFFICE Document Server
LDAP/Active Directory 伺服器 (企業環境)
SMTP 郵件伺服器

一鍵啟動

Windows 環境

# 使用自動化腳本啟動
start-windows.bat

# 或手動執行
docker-compose up -d
docker-compose exec app python init_db.py

Linux 環境

# 使用自動化腳本啟動
chmod +x start-linux.sh
./start-linux.sh

# 或手動執行
docker-compose up -d
docker-compose exec app python init_db.py

2. 平台特定部署

2.1 Windows 部署

開發環境

準備環境

# 建立虛擬環境
python -m venv venv
venv\Scripts\activate

# 安裝依賴
pip install -r requirements.txt

設定環境變數

copy .env.example .env
# 編輯 .env 檔案設定參數

啟動外部服務

# 啟動 MySQL (使用 Docker)
docker run -d --name tempspec-mysql ^
  -e MYSQL_ROOT_PASSWORD=tempspec123 ^
  -e MYSQL_DATABASE=tempspec_db ^
  -e MYSQL_USER=tempspec_user ^
  -e MYSQL_PASSWORD=tempspec_pass ^
  -p 3306:3306 mysql:8.0

# 啟動 ONLYOFFICE
docker run -d --name tempspec-onlyoffice ^
  -e JWT_ENABLED=true ^
  -e JWT_SECRET=your_jwt_secret ^
  -p 8080:80 onlyoffice/documentserver

初始化並啟動應用

python init_db.py
python app.py

生產環境 (Windows Server + IIS)

安裝 IIS 和 HttpPlatformHandler
- 啟用 IIS 功能
- 安裝 HttpPlatformHandler 模組
建立應用程式目錄

mkdir C:\inetpub\wwwroot\tempspec
xcopy /E /I . C:\inetpub\wwwroot\tempspec

建立 Web.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="PythonHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="C:\Python310\python.exe"
                  arguments="app.py"
                  startupTimeLimit="60"
                  startupRetryCount="3"
                  stdoutLogEnabled="true"
                  stdoutLogFile="logs\python.log"
                  environmentVariables="PYTHONPATH=C:\inetpub\wwwroot\tempspec">
      <environmentVariables>
        <environmentVariable name="PYTHONPATH" value="C:\inetpub\wwwroot\tempspec" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

使用 Waitress (建議方式)

pip install waitress
waitress-serve --host=0.0.0.0 --port=5000 app:app

Windows 服務安裝

使用 NSSM (Non-Sucking Service Manager):

# 下載 NSSM
# https://nssm.cc/download

# 安裝服務
nssm install TempSpecSystem

# 設定參數
nssm set TempSpecSystem Application "C:\path\to\python.exe"
nssm set TempSpecSystem AppParameters "app.py"
nssm set TempSpecSystem AppDirectory "C:\path\to\your\app"
nssm set TempSpecSystem DisplayName "Temp Spec System V3"
nssm set TempSpecSystem Description "企業暫時規範管理系統"

# 啟動服務
nssm start TempSpecSystem

2.2 Linux 部署

開發環境

準備環境 (Ubuntu/Debian)

# 更新系統
sudo apt update && sudo apt upgrade -y

# 安裝必要套件
sudo apt install python3 python3-pip python3-venv git curl -y

# 建立虛擬環境
python3 -m venv venv
source venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

CentOS/RHEL 環境

# 安裝 EPEL repository
sudo yum install epel-release -y

# 安裝必要套件
sudo yum install python3 python3-pip git curl -y

# 建立虛擬環境
python3 -m venv venv
source venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

生產環境 (Nginx + Gunicorn)

安裝 Gunicorn

pip install gunicorn gevent

建立 Gunicorn 設定檔

# gunicorn.conf.py
bind = "127.0.0.1:5000"
workers = 4
worker_class = "gevent"
worker_connections = 1000
max_requests = 1000
max_requests_jitter = 50
timeout = 30
keepalive = 2
preload_app = True

建立 systemd 服務檔案

sudo nano /etc/systemd/system/tempspec.service

[Unit]
Description=Temp Spec System V3
After=network.target mysql.service

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/path/to/your/app
Environment="PATH=/path/to/your/app/venv/bin"
ExecStart=/path/to/your/app/venv/bin/gunicorn -c gunicorn.conf.py app:app
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

啟動服務

sudo systemctl daemon-reload
sudo systemctl enable tempspec
sudo systemctl start tempspec
sudo systemctl status tempspec

設定 Nginx

sudo nano /etc/nginx/sites-available/tempspec

server {
    listen 80;
    server_name your-domain.com;
    
    # SSL 重定向 (生產環境建議)
    # return 301 https://$server_name$request_uri;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支援
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
    
    # 靜態檔案
    location /static/ {
        alias /path/to/your/app/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    
    # 大檔案上傳支援
    client_max_body_size 100M;
}

啟用站點

sudo ln -s /etc/nginx/sites-available/tempspec /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

3. Docker 部署

3.1 基本 Docker 部署

# 1. 複製環境設定檔
cp .env.example .env
# 編輯 .env 設定參數

# 2. 啟動所有服務
docker-compose up -d

# 3. 初始化資料庫
docker-compose exec app python init_db.py

# 4. 檢查服務狀態
docker-compose ps

3.2 開發環境部署

# 使用 override 檔案啟動開發環境
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

# 查看即時日誌
docker-compose logs -f app

3.3 生產環境部署

# 啟動包含 Nginx 的完整生產環境
docker-compose --profile production up -d

# 檢查所有服務
docker-compose ps

3.4 Docker Swarm 部署 (高可用性)

初始化 Swarm

docker swarm init

建立 Docker Stack 檔案

# docker-stack.yml
version: '3.8'

services:
  app:
    image: tempspec:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
    networks:
      - tempspec-network
    
  mysql:
    image: mysql:8.0
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.role == manager
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - tempspec-network

networks:
  tempspec-network:
    external: true

volumes:
  mysql_data:

部署 Stack

docker stack deploy -c docker-stack.yml tempspec

3.5 Docker 管理指令

# 查看服務狀態
docker-compose ps

# 查看日誌
docker-compose logs -f [service_name]

# 重啟服務
docker-compose restart [service_name]

# 進入容器
docker-compose exec app bash

# 備份資料庫
docker-compose exec mysql mysqldump -u root -p tempspec_db > backup.sql

# 清理未使用的資源
docker system prune -f
docker volume prune -f

4. 生產環境部署

4.1 負載均衡部署

使用多個應用程式實例提高可用性：

# docker-compose.prod.yml
version: '3.8'

services:
  app1:
    build: .
    environment:
      - INSTANCE_ID=1
    # 其他設定...

  app2:
    build: .
    environment:
      - INSTANCE_ID=2
    # 其他設定...

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx/nginx-lb.conf:/etc/nginx/nginx.conf
    ports:
      - "80:80"
    depends_on:
      - app1
      - app2

4.2 SSL/HTTPS 設定

獲取 SSL 證書 (Let's Encrypt)

# 安裝 Certbot
sudo apt install certbot python3-certbot-nginx

# 獲取證書
sudo certbot --nginx -d your-domain.com

Docker 環境 SSL 設定

# docker-compose.ssl.yml
version: '3.8'

services:
  nginx:
    volumes:
      - /etc/letsencrypt:/etc/letsencrypt:ro
      - ./nginx/ssl.conf:/etc/nginx/conf.d/default.conf
    ports:
      - "443:443"
      - "80:80"

4.3 監控和日誌

集成監控 (可選)

# 添加到 docker-compose.yml
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

集中化日誌收集

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.14.0
    environment:
      - discovery.type=single-node
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    
  kibana:
    image: docker.elastic.co/kibana/kibana:7.14.0
    ports:
      - "5601:5601"

4.4 備份策略

資料庫備份腳本

#!/bin/bash
# backup-db.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/mysql"
CONTAINER_NAME="tempspec-mysql"

mkdir -p $BACKUP_DIR

# 備份資料庫
docker exec $CONTAINER_NAME mysqldump \
  -u root -p$MYSQL_ROOT_PASSWORD \
  tempspec_db > $BACKUP_DIR/tempspec_$DATE.sql

# 壓縮備份檔案
gzip $BACKUP_DIR/tempspec_$DATE.sql

# 刪除 30 天前的備份
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete

echo "Database backup completed: tempspec_$DATE.sql.gz"

設定 cron 自動備份

# 編輯 crontab
crontab -e

# 每天凌晨 2:30 執行備份
30 2 * * * /path/to/backup-db.sh >> /var/log/tempspec-backup.log 2>&1

5. 疑難排解

5.1 常見問題

問題：Docker 容器無法啟動

可能原因：

端口被占用
環境變數設定錯誤
磁碟空間不足

解決方案：

# 檢查端口占用
netstat -tulpn | grep :5000

# 檢查容器日誌
docker-compose logs app

# 檢查磁碟空間
df -h

# 清理 Docker 資源
docker system prune -a

問題：LDAP 連線失敗

檢查清單：

LDAP 伺服器地址正確
防火牆開放 389/636 端口
服務帳號權限足夠
搜尋基底設定正確

測試 LDAP 連線：

# 使用 ldapsearch 測試
ldapsearch -H ldap://your-dc.company.com -D "CN=service,DC=company,DC=com" -W -b "DC=company,DC=com"

# 或在 Python 中測試
python3 -c "
from ldap_utils import authenticate_ldap_user
result = authenticate_ldap_user('testuser', 'testpass')
print('LDAP Test Result:', result)
"

問題：ONLYOFFICE 編輯器載入失敗

檢查項目：

Document Server 容器運行正常
JWT Secret 設定一致
網路連線可達
瀏覽器支援 WebSocket

測試方法：

# 檢查 ONLYOFFICE 健康狀態
curl http://localhost:8080/healthcheck

# 檢查容器狀態
docker logs tempspec-onlyoffice

# 測試 JWT 設定
docker exec tempspec-onlyoffice cat /etc/onlyoffice/documentserver/default.json | grep -i jwt

問題：排程任務未執行

檢查步驟：

確認 APScheduler 已初始化
檢查應用程式日誌
驗證任務註冊

# 在 Flask shell 中檢查任務
from app import scheduler
print(scheduler.get_jobs())

5.2 效能調校

資料庫最佳化

-- 檢查慢查詢
SHOW VARIABLES LIKE 'slow_query_log';
SHOW VARIABLES LIKE 'long_query_time';

-- 分析資料表
ANALYZE TABLE ts_temp_spec;
ANALYZE TABLE ts_user;
ANALYZE TABLE ts_upload;

-- 建立必要索引
CREATE INDEX idx_spec_status ON ts_temp_spec(status);
CREATE INDEX idx_spec_end_date ON ts_temp_spec(end_date);
CREATE INDEX idx_history_spec_id ON ts_spec_history(spec_id);

應用程式最佳化

# config.py 調整
class ProductionConfig(Config):
    # 資料庫連線池設定
    SQLALCHEMY_ENGINE_OPTIONS = {
        'pool_size': 20,
        'pool_recycle': 300,
        'pool_pre_ping': True
    }
    
    # Redis 快取 (可選)
    CACHE_TYPE = 'redis'
    CACHE_REDIS_URL = 'redis://redis:6379/0'

5.3 監控指標

重要的監控指標：

應用程式指標
- 回應時間
- 錯誤率
- 記憶體使用率
- CPU 使用率
資料庫指標
- 連線數
- 查詢執行時間
- 緩衝池命中率
系統指標
- 磁碟使用率
- 網路流量
- 檔案描述符使用率

# 系統監控腳本範例
#!/bin/bash
# monitor.sh

echo "=== System Status ==="
echo "CPU Usage: $(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)"
echo "Memory Usage: $(free | grep Mem | awk '{printf("%.1f%%", $3/$2 * 100.0)}')"
echo "Disk Usage: $(df -h | grep '/$' | awk '{print $5}')"

echo "=== Docker Status ==="
docker stats --no-stream --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}"

echo "=== Application Status ==="
curl -s http://localhost:5000/health | jq .

本部署指南涵蓋了大部分常見的部署場景。如果遇到特殊情況或需要客製化部署，請參考系統相關文檔。

14 KiB Raw Permalink Blame History Unescape Escape

部署指南 - 暫時規範管理系統 V3

📋 目錄

1. 快速開始

前置需求檢查清單

一鍵啟動

Windows 環境

Linux 環境

2. 平台特定部署

2.1 Windows 部署

開發環境

生產環境 (Windows Server + IIS)

Windows 服務安裝

2.2 Linux 部署

開發環境

生產環境 (Nginx + Gunicorn)

3. Docker 部署

3.1 基本 Docker 部署

3.2 開發環境部署

3.3 生產環境部署

3.4 Docker Swarm 部署 (高可用性)

3.5 Docker 管理指令

4. 生產環境部署

4.1 負載均衡部署

4.2 SSL/HTTPS 設定

4.3 監控和日誌

4.4 備份策略

5. 疑難排解

5.1 常見問題

問題：Docker 容器無法啟動

問題：LDAP 連線失敗

問題：ONLYOFFICE 編輯器載入失敗

問題：排程任務未執行

5.2 效能調校

資料庫最佳化

應用程式最佳化

5.3 監控指標

14 KiB

Raw Permalink Blame History