482 lines
12 KiB
Markdown
482 lines
12 KiB
Markdown
# 部署指南 - 暫時規範管理系統 V4
|
||
|
||
本文件提供詳細的部署指導，涵蓋 Docker 環境部署方式及 V4 版本的新特性配置。
|
||
|
||
## 🎉 V4.0 版本優化完成
|
||
|
||
**✅ 已完成企業級生產環境優化**：
|
||
- 台灣時區 (GMT+8) 完整支援
|
||
- 展延次數限制功能（最多2次，90天上限）
|
||
- OnlyOffice 文件同步問題修正
|
||
- Redis 快取系統（提升效能）
|
||
- Nginx 反向代理（負載均衡）
|
||
- 容器間網路優化
|
||
- 時區處理模組化
|
||
- UI 樣式改進
|
||
|
||
## 📋 目錄
|
||
|
||
1. [系統需求](#1-系統需求)
|
||
2. [快速部署](#2-快速部署)
|
||
3. [生產環境配置](#3-生產環境配置)
|
||
4. [V4.0 新功能配置](#4-v40-新功能配置)
|
||
5. [監控與管理](#5-監控與管理)
|
||
6. [服務訪問](#6-服務訪問)
|
||
7. [疑難排解](#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. 快速部署
|
||
|
||
### 一鍵部署（推薦）
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
```bash
|
||
# 5. 查看服務日誌
|
||
docker-compose logs -f
|
||
|
||
# 6. 驗證服務可訪問性
|
||
curl -I http://localhost:12013/login # Nginx 反向代理（推薦）
|
||
curl -I http://localhost:12015 # OnlyOffice 服務
|
||
```
|
||
|
||
### 初始化資料庫
|
||
|
||
```bash
|
||
# 初始化資料庫結構
|
||
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` 檔案：
|
||
|
||
```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`
|
||
- 資料庫時間自動轉換為台灣時區
|
||
|
||
**驗證時區設定**：
|
||
```bash
|
||
# 檢查容器時區
|
||
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天
|
||
- 前端按鈕自動禁用
|
||
- 後端邏輯驗證
|
||
|
||
**配置驗證**：
|
||
```bash
|
||
# 檢查展延限制邏輯
|
||
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 處理
|
||
- 修正容器間網路通信
|
||
|
||
**同步測試**：
|
||
```bash
|
||
# 測試 OnlyOffice 網路連接
|
||
docker exec panjit-tempspec-onlyoffice curl -I http://panjit-tempspec-nginx:80/
|
||
|
||
# 檢查回調處理日誌
|
||
docker-compose logs app | grep "OnlyOffice callback"
|
||
```
|
||
|
||
### 4.4 Redis 快取系統
|
||
|
||
**配置檢查**：
|
||
```bash
|
||
# 檢查 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 系統監控
|
||
|
||
```bash
|
||
# 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 特定檢查
|
||
|
||
```bash
|
||
# 時區功能檢查
|
||
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 快取管理
|
||
|
||
```bash
|
||
# 快取狀態檢查
|
||
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 特定問題
|
||
|
||
**時區顯示錯誤**
|
||
```bash
|
||
# 檢查容器時區設定
|
||
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
|
||
```
|
||
|
||
**展延限制未生效**
|
||
```bash
|
||
# 檢查展延邏輯
|
||
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 文件同步問題**
|
||
```bash
|
||
# 檢查 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 快取問題**
|
||
```bash
|
||
# 檢查 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 容器網路問題
|
||
|
||
**容器間通信失敗**
|
||
```bash
|
||
# 檢查網路配置
|
||
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
|
||
```
|
||
|
||
**端口衝突解決**
|
||
```bash
|
||
# 檢查端口占用
|
||
netstat -tulpn | grep -E "(12013|12015)"
|
||
|
||
# 修改端口配置（編輯 docker-compose.yml）
|
||
# 將衝突端口改為其他可用端口
|
||
```
|
||
|
||
### 7.3 資料庫連接問題
|
||
|
||
**MySQL 連接測試**
|
||
```bash
|
||
# 測試外部資料庫連接
|
||
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 維護命令
|
||
|
||
```bash
|
||
# 完全重建 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 效能監控
|
||
|
||
```bash
|
||
# 監控容器資源使用
|
||
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 部署完成！**
|
||
|
||
系統已具備完整的台灣時區支援、展延限制控制、優化的文件同步機制以及增強的用戶體驗。 |