TEMP_spec_system/DEPLOYMENT.md

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

本文件提供詳細的部署指導，涵蓋 Docker 環境部署方式及 V4 版本的新特性配置。

🎉 V4.0 版本優化完成

✅ 已完成企業級生產環境優化：

• 台灣時區 (GMT+8) 完整支援
• 展延次數限制功能（最多2次，90天上限）
• OnlyOffice 文件同步問題修正
• Redis 快取系統（提升效能）
• Nginx 反向代理（負載均衡）
• 容器間網路優化
• 時區處理模組化
• UI 樣式改進

📋 目錄

1. 系統需求
2. 快速部署
3. 生產環境配置
4. V4.0 新功能配置
5. 監控與管理
6. 服務訪問
7. 疑難排解

1. 系統需求

前置需求檢查清單

• Docker 20.10+ 已安裝且運行中
• Docker Compose 2.0+ 已安裝
• 外部 MySQL 資料庫可訪問 (mysql.theaken.com:33306)
• LDAP/Active Directory 伺服器可連線 (panjit.com.tw)
• SMTP 郵件伺服器已配置 (mail.panjit.com.tw)
• 足夠的磁碟空間 (建議至少 10GB)

端口需求

確保以下端口未被占用：

• 12010: Flask 應用程式（內部，可選直接訪問）
• 12013: Nginx HTTP（反向代理，主要入口）
• 12015: OnlyOffice 文檔服務
• 6379: Redis 快取（容器內部）

V4.0 網路架構

用戶 → Nginx (12013) → Flask App (5000) → MySQL (外部)
                     ↓                  ↓
                  Redis (6379)     OnlyOffice (80)

2. 快速部署

一鍵部署（推薦）

# 1. 克隆專案
git clone <repository-url>
cd TEMP_spec_system_V4

# 2. 配置環境變數（使用預設配置）
cp .env.example .env
# 編輯 .env 文件，大部分配置已預設好

# 3. 啟動所有服務（V4.0優化版本）
docker-compose up -d --build

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

預期輸出應包含以下服務：

NAME                        STATUS              PORTS
panjit-tempspec-redis       Up (healthy)
panjit-tempspec-onlyoffice  Up (healthy)        0.0.0.0:12015->80/tcp
panjit-tempspec-app         Up (healthy)
panjit-tempspec-nginx       Up                  0.0.0.0:12013->80/tcp

# 5. 查看服務日誌
docker-compose logs -f

# 6. 驗證服務可訪問性
curl -I http://localhost:12013/login    # Nginx 反向代理（推薦）
curl -I http://localhost:12015          # OnlyOffice 服務

初始化資料庫

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

# 檢查資料庫連接
docker-compose exec app python -c "
from app import app
from models import db
with app.app_context():
    try:
        db.engine.execute('SELECT 1')
        print('✅ Database connection successful')
    except Exception as e:
        print(f'❌ Database connection failed: {e}')
"

3. 生產環境配置

3.1 服務架構（V4.0 優化）

外部用戶 → Nginx (12013) → Flask App (Gunicorn) → 外部MySQL
                         ↓                      ↓
                    Redis快取           OnlyOffice (12015)
                         ↓
                   台灣時區處理模組

V4.0 服務組件：

• Nginx: 反向代理 + 靜態檔案（端口 12013）
• Flask 應用: Gunicorn WSGI 伺服器（內部端口 5000）
• Redis: 快取系統（內部端口 6379）
• OnlyOffice: 文檔編輯服務（端口 12015）
• MySQL: 外部資料庫服務（mysql.theaken.com:33306）

3.2 V4.0 效能規格

• 時區支援: 全系統台灣時區 (GMT+8) 處理
• 展延控制: 最多2次展延，90天效期上限
• 文件同步: 增強的 OnlyOffice 回調處理
• 快取優化: Redis 減少資料庫查詢負載
• 網路優化: 容器間通信使用服務名稱
• 響應時間: < 200ms（快取命中時）

3.3 環境變數配置

編輯 .env 檔案：

# V4.0 基本設定
SECRET_KEY=your_super_secret_production_key_here
FLASK_ENV=production

# 外部 MySQL 資料庫
DATABASE_URL=mysql+pymysql://A060:WLeSCi0yhtc7@mysql.theaken.com:33306/db_A060

# Redis 快取
REDIS_URL=redis://redis:6379/0

# LDAP 設定（V4.0預設配置）
LDAP_SERVER=panjit.com.tw
LDAP_PORT=389
LDAP_USE_SSL=false
LDAP_SEARCH_BASE=DC=panjit,DC=com,DC=tw
LDAP_BIND_USER_DN=CN=LdapBind,CN=Users,DC=PANJIT,DC=COM,DC=TW
LDAP_BIND_USER_PASSWORD=panjit2481
LDAP_USER_LOGIN_ATTR=userPrincipalName

# SMTP 設定（V4.0預設配置）
SMTP_SERVER=mail.panjit.com.tw
SMTP_PORT=25
SMTP_USE_TLS=false
SMTP_USE_SSL=false
SMTP_AUTH_REQUIRED=false
SMTP_SENDER_EMAIL=temp-spec-system@panjit.com.tw
SMTP_SENDER_PASSWORD=

# OnlyOffice 設定
ONLYOFFICE_URL=http://localhost:12015/
ONLYOFFICE_INTERNAL_URL=http://onlyoffice:80
ONLYOFFICE_JWT_SECRET=your_jwt_secret_key_here

# 服務端口設定
ONLYOFFICE_PORT=12015

4. V4.0 新功能配置

4.1 台灣時區支援

自動配置：

• Docker 容器環境變數：TZ: Asia/Taipei
• Python 時區模組：utils/timezone.py
• 資料庫時間自動轉換為台灣時區

驗證時區設定：

# 檢查容器時區
docker exec panjit-tempspec-app date

# 測試 Python 時區功能
docker exec panjit-tempspec-app python -c "
from utils.timezone import taiwan_now, format_taiwan_time
print('Current Taiwan time:', format_taiwan_time(taiwan_now()))
"

4.2 展延次數限制

功能說明：

• 每個暫時規範最多展延2次
• 總效期上限90天
• 前端按鈕自動禁用
• 後端邏輯驗證

配置驗證：

# 檢查展延限制邏輯
docker exec panjit-tempspec-app python -c "
from app import app
with app.app_context():
    print('Extension limit logic loaded successfully')
"

4.3 OnlyOffice 文件同步

V4.0 改進：

• 支援多種儲存狀態（status=2, status=6）
• 增強回調 URL 處理
• 修正容器間網路通信

同步測試：

# 測試 OnlyOffice 網路連接
docker exec panjit-tempspec-onlyoffice curl -I http://panjit-tempspec-nginx:80/

# 檢查回調處理日誌
docker-compose logs app | grep "OnlyOffice callback"

4.4 Redis 快取系統

配置檢查：

# 檢查 Redis 連接
docker-compose exec redis redis-cli ping

# 查看快取統計
docker-compose exec redis redis-cli info stats

# 監控快取使用
docker-compose exec redis redis-cli monitor

5. 監控與管理

5.1 系統監控

# V4.0 系統監控（如有 monitor.py）
python monitor.py --watch 5

# Docker 容器監控
docker-compose ps
docker stats

# 服務健康檢查
docker-compose logs --tail=50 app
docker-compose logs --tail=50 nginx
docker-compose logs --tail=50 redis
docker-compose logs --tail=50 onlyoffice

5.2 V4.0 特定檢查

# 時區功能檢查
docker exec panjit-tempspec-app python -c "
from utils.timezone import taiwan_now, to_taiwan_time
from datetime import datetime
print('Taiwan now:', taiwan_now())
print('UTC to Taiwan:', to_taiwan_time(datetime.utcnow()))
"

# 展延限制檢查
docker exec panjit-tempspec-app python -c "
from models import TempSpec
from app import app
with app.app_context():
    specs = TempSpec.query.filter(TempSpec.extension_count >= 2).count()
    print(f'Specs at extension limit: {specs}')
"

# OnlyOffice 同步檢查
docker-compose logs app | grep -E "(callback|sync|save)" | tail -10

5.3 Redis 快取管理

# 快取狀態檢查
docker-compose exec redis redis-cli info memory
docker-compose exec redis redis-cli dbsize

# 清空快取（如需要）
docker-compose exec redis redis-cli flushall

# 監控快取命中率
docker-compose exec redis redis-cli info stats | grep hit

6. 服務訪問

6.1 V4.0 服務入口

主要服務：

• 主應用程式 (Nginx): http://localhost:12013 🌟 推薦
• OnlyOffice 服務: http://localhost:12015

V4.0 登入資訊：

• 認證方式: LDAP/Active Directory
• 登入格式: username@panjit.com.tw
• 時區顯示: 所有時間使用台灣時區 (GMT+8)

6.2 V4.0 新功能驗證

登入後驗證以下新功能：

1. 時區顯示: 檢查所有時間是否使用台灣時區
2. 展延限制: 查看已展延2次的規範是否正確顯示限制
3. 文件同步: 測試 OnlyOffice 編輯和儲存功能
4. UI 改進: 檢查展延狀態在深色背景下的可讀性

7. 疑難排解

7.1 V4.0 特定問題

時區顯示錯誤

# 檢查容器時區設定
docker exec panjit-tempspec-app date
docker exec panjit-tempspec-app python -c "
import os
print('TZ:', os.environ.get('TZ', 'Not set'))
"

# 重新啟動應用容器
docker-compose restart app

展延限制未生效

# 檢查展延邏輯
docker-compose logs app | grep -i extension

# 測試展延限制邏輯
docker exec panjit-tempspec-app python -c "
from routes.temp_spec import check_extension_limit
print('Extension limit logic available')
"

OnlyOffice 文件同步問題

# 檢查 OnlyOffice 回調
docker-compose logs app | grep "OnlyOffice callback"

# 檢查容器間網路
docker exec panjit-tempspec-onlyoffice ping panjit-tempspec-nginx

# 檢查 OnlyOffice 健康狀態
curl -I http://localhost:12015/healthcheck

Redis 快取問題

# 檢查 Redis 連接
docker-compose exec app python -c "
import redis
r = redis.Redis(host='redis', port=6379, db=0)
print('Redis ping:', r.ping())
"

# 重啟 Redis
docker-compose restart redis

7.2 容器網路問題

容器間通信失敗

# 檢查網路配置
docker network ls | grep tempspec
docker network inspect tempspec-network

# 測試容器間連接
docker exec panjit-tempspec-app ping panjit-tempspec-redis
docker exec panjit-tempspec-app ping panjit-tempspec-onlyoffice
docker exec panjit-tempspec-app ping panjit-tempspec-nginx

端口衝突解決

# 檢查端口占用
netstat -tulpn | grep -E "(12013|12015)"

# 修改端口配置（編輯 docker-compose.yml）
# 將衝突端口改為其他可用端口

7.3 資料庫連接問題

MySQL 連接測試

# 測試外部資料庫連接
docker-compose exec app python -c "
import pymysql
try:
    conn = pymysql.connect(
        host='mysql.theaken.com',
        port=33306,
        user='A060',
        password='WLeSCi0yhtc7',
        database='db_A060'
    )
    print('✅ Database connection successful')
    conn.close()
except Exception as e:
    print(f'❌ Database connection failed: {e}')
"

7.4 V4.0 維護命令

# 完全重建 V4.0 服務
docker-compose down
docker-compose build --no-cache
docker-compose up -d

# 更新單一服務
docker-compose up -d --force-recreate app

# 清理 Docker 資源
docker system prune -a

# 備份重要資料
docker exec panjit-tempspec-app tar -czf /tmp/uploads_backup.tar.gz uploads/
docker cp panjit-tempspec-app:/tmp/uploads_backup.tar.gz ./uploads_backup.tar.gz

7.5 V4.0 效能監控

# 監控容器資源使用
docker stats panjit-tempspec-app panjit-tempspec-redis panjit-tempspec-nginx

# 檢查應用效能
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:12013/login

# Redis 效能監控
docker-compose exec redis redis-cli info stats | grep -E "(hits|misses|ops)"

---

🎉 V4.0 部署完成檢查清單

• 所有容器運行正常 (docker-compose ps)
• 時區顯示為台灣時區 (GMT+8)
• 展延限制功能正常 (最多2次)
• OnlyOffice 文件同步正常
• Redis 快取服務運行
• Nginx 反向代理正常
• LDAP 認證功能正常
• 郵件通知功能正常
• UI 樣式顯示正確

快速啟動: docker-compose up -d --build 服務訪問: http://localhost:12013 健康檢查: docker-compose ps && docker-compose logs --tail=10

---

🚀 暫時規範管理系統 V4.0 部署完成！

系統已具備完整的台灣時區支援、展延限制控制、優化的文件同步機制以及增強的用戶體驗。