366 lines
9.8 KiB
Markdown
366 lines
9.8 KiB
Markdown
# 🔧 NFC 生產工具
|
||
|
||
## 📋 專案概述
|
||
|
||
這是一個整合式的 NFC 生產工具，結合了 C 語言核心程式與 Flask Web 介面，提供完整的 NFC 卡片生產、認證和管理功能。支援 SDM 加密、CMAC 認證、API 整合等進階功能。
|
||
|
||
### 🎯 主要功能
|
||
- **📝 生產新SDM**：完整的 SDM 生產流程（變更金鑰 → 設定SDM → CMAC認證 → API上傳）
|
||
- **🔍 檢驗NFC**：本地認證成功後自動POST到檢驗API
|
||
- **🔐 本地CMAC認證**：本地認證 + 遠端線上認證
|
||
- **🧪 完整測試NFC**：預處理 + 完整功能測試
|
||
- **📖 讀取UID**：批次讀取所有NFC卡片
|
||
- **Web 管理介面**：直觀的網頁操作介面
|
||
- **URL 管理**：線上編輯和管理 URLs.txt
|
||
- **即時監控**：WebSocket 即時顯示執行狀態
|
||
- **API 整合**：支援 Bearer Token 認證的 API 通訊
|
||
|
||
## 🚀 快速開始
|
||
|
||
### 1. 系統需求
|
||
- **作業系統**：Ubuntu 18.04+ / CentOS 7+ / Debian 9+
|
||
- **Python**：3.7 或以上版本
|
||
- **硬體**：uFR NFC 讀卡機
|
||
- **網路**：用於 API 通訊和遠端認證
|
||
|
||
### 2. 一鍵安裝
|
||
```bash
|
||
# 下載專案
|
||
git clone <repository-url>
|
||
cd ufr_zero_nt4h(WEB)
|
||
|
||
# 執行安裝腳本
|
||
chmod +x install.sh
|
||
./install.sh
|
||
```
|
||
|
||
**安裝腳本功能**：
|
||
- 🔍 自動檢測作業系統（Ubuntu/Debian/CentOS/RHEL）
|
||
- 📦 自動安裝系統依賴套件
|
||
- 🔌 設定 USB 裝置權限（uFR 讀卡機）
|
||
- 🐍 創建 Python 虛擬環境
|
||
- 📁 設定檔案權限
|
||
- ⚙️ 可選創建 systemd 服務
|
||
- 🧹 自動清理現有服務配置
|
||
|
||
### 3. 手動安裝
|
||
```bash
|
||
# 1. 安裝 Python 依賴
|
||
pip install -r requirements.txt
|
||
|
||
# 2. 設定執行權限
|
||
chmod +x linux64_release/nt4h_c_example
|
||
chmod +x start.sh
|
||
|
||
# 3. 啟動應用程式
|
||
./start.sh
|
||
```
|
||
|
||
### 4. 啟動方式
|
||
|
||
#### 方式一：直接啟動
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
#### 方式二：背景執行
|
||
```bash
|
||
nohup ./start.sh > app.log 2>&1 &
|
||
```
|
||
|
||
#### 方式三：systemd 服務（推薦）
|
||
```bash
|
||
# 啟動服務
|
||
sudo systemctl start NFCapp.service
|
||
|
||
# 啟用開機自啟
|
||
sudo systemctl enable NFCapp.service
|
||
|
||
# 查看服務狀態
|
||
sudo systemctl status NFCapp.service
|
||
|
||
# 查看服務日誌
|
||
sudo journalctl -u NFCapp.service -f
|
||
```
|
||
|
||
### 5. 訪問應用程式
|
||
開啟瀏覽器訪問：`http://localhost:5000`
|
||
|
||
## 🔧 安裝腳本詳解
|
||
|
||
### install.sh 功能說明
|
||
|
||
安裝腳本 `install.sh` 提供完整的自動化安裝流程：
|
||
|
||
#### 🔍 系統檢測
|
||
- 自動檢測作業系統類型（Ubuntu/Debian/CentOS/RHEL）
|
||
- 檢查 Python 版本（需要 3.7+）
|
||
- 驗證必要檔案存在
|
||
|
||
#### 📦 依賴安裝
|
||
- **Ubuntu/Debian**：安裝 python3, python3-pip, python3-venv, gcc, make, curl, wget
|
||
- **CentOS/RHEL**：安裝 python3, python3-pip, gcc, make, curl, wget
|
||
|
||
#### 🔌 USB 權限設定
|
||
- 創建 udev 規則檔案 `/etc/udev/rules.d/99-ufr.rules`
|
||
- 支援多種 uFR 讀卡機型號（6001, 6014, 6015）
|
||
- 自動將使用者加入 dialout 群組
|
||
- 重新載入 udev 規則
|
||
|
||
#### 🐍 Python 環境
|
||
- 檢查並重新創建虛擬環境（如果已存在）
|
||
- 升級 pip 到最新版本
|
||
- 安裝 requirements.txt 中的所有依賴
|
||
|
||
#### 📁 檔案權限
|
||
- 設定執行檔權限
|
||
- 設定設定檔權限（keys.txt, urls.txt）
|
||
|
||
#### ⚙️ systemd 服務管理
|
||
- **自動清理**：檢查並刪除現有的 `NFCapp.service`
|
||
- **服務停止**：停止正在運行的服務
|
||
- **服務禁用**：禁用已啟用的服務
|
||
- **檔案刪除**：刪除舊的服務檔案
|
||
- **配置重載**：重新載入 systemd 配置
|
||
- **可選創建**：詢問使用者是否創建新的 systemd 服務
|
||
|
||
#### 🎨 使用者體驗
|
||
- 彩色日誌輸出（INFO, SUCCESS, WARNING, ERROR）
|
||
- 詳細的安裝進度顯示
|
||
- 完整的安裝完成資訊
|
||
- 服務管理指令說明
|
||
|
||
## 🎮 使用說明
|
||
|
||
### 主要操作
|
||
|
||
#### 📝 生產新SDM
|
||
完整的 SDM 生產流程：
|
||
1. 自動尋找可用的 oldkey
|
||
2. 變更金鑰到選擇的 KEY
|
||
3. 設定 SDM 功能
|
||
4. 執行 CMAC 認證
|
||
5. 自動 POST 到生產 API
|
||
|
||
**API 端點**：`{API_URL}/nfc/insertForProduction`
|
||
**POST 格式**：
|
||
```json
|
||
{
|
||
"uid": "04296A5AD51F90",
|
||
"ctr": "00000A",
|
||
"key": "1"
|
||
}
|
||
```
|
||
|
||
#### 🔍 檢驗NFC
|
||
檢驗現有 NFC 卡片：
|
||
1. 執行本地 CMAC 認證
|
||
2. 解析 UID
|
||
3. 自動 POST 到檢驗 API
|
||
|
||
**API 端點**：`{API_URL}/nfc/verifyForProduction`
|
||
**POST 格式**：
|
||
```json
|
||
{
|
||
"uid": "04296A5AD51F90"
|
||
}
|
||
```
|
||
|
||
#### 🔐 本地CMAC認證
|
||
雙重認證流程：
|
||
1. 本地 CMAC 認證
|
||
2. 遠端線上認證（https://verify.contree.app/verify）
|
||
|
||
#### 🧪 完整測試NFC
|
||
預處理 + 完整測試：
|
||
1. 讀取 UID 尋找可用 KEY
|
||
2. 強制更換到 key 1
|
||
3. 執行完整測試腳本
|
||
|
||
#### 📖 讀取UID
|
||
批次讀取所有 NFC 卡片，找到第一個可讀取的卡片後停止。
|
||
|
||
### 設定選項
|
||
- **選擇 Key**：選擇要使用的金鑰（從 keys.txt）
|
||
- **選擇 URL**：選擇要寫入的 URL（從 urls.txt）
|
||
- **選擇 NFC 名稱**：選擇或新增 NFC 卡片名稱
|
||
- **資料API URL**：設定 API 伺服器位址
|
||
- **API Token**：設定 Bearer Token 認證
|
||
|
||
### 工具操作
|
||
- **🔄 重新整理選項**：重新載入 keys.txt 和 urls.txt
|
||
- **🗑️ 清除執行結果**：清除輸出區域內容
|
||
- **✏️ 編輯URL**：開啟 URL 編輯視窗
|
||
- **⬇️ 到底部**：自動滾動到輸出底部
|
||
- **⬆️ 到頂部**：自動滾動到輸出頂部
|
||
|
||
## 📁 檔案結構
|
||
|
||
```
|
||
ufr_zero_nt4h(WEB)/
|
||
├── app.py # Flask Web 應用程式主檔
|
||
├── start.sh # Linux 啟動腳本
|
||
├── requirements.txt # Python 依賴套件
|
||
├── config.json # 應用程式設定檔
|
||
├── templates/
|
||
│ ├── index.html # 主頁面
|
||
│ └── manual_test.html # 手動測試頁面
|
||
├── linux64_release/ # Linux 64位執行檔目錄
|
||
│ ├── nt4h_c_example # 核心 NFC 程式
|
||
│ ├── keys.txt # 金鑰檔案
|
||
│ ├── urls.txt # URL 設定檔
|
||
│ └── libnt4h_c.so # uFR 函式庫
|
||
└── src/ # C 語言原始碼
|
||
├── main.c # 主程式
|
||
├── uFR.c # uFR 介面
|
||
└── utils.c # 工具函式
|
||
```
|
||
|
||
## ⚙️ 設定說明
|
||
|
||
### config.json
|
||
```json
|
||
{
|
||
"api_url": "https://your-api-server.com",
|
||
"api_token": "Bearer eyJhbGciOiJIUzI1NiJ9...",
|
||
"name": "default-name",
|
||
"names": ["name1", "name2"]
|
||
}
|
||
```
|
||
|
||
### API 設定
|
||
- **資料API URL**：設定 API 伺服器基礎位址
|
||
- **API Token**：設定 Bearer Token 用於 API 認證
|
||
- **自動認證**：所有 API 請求都會自動包含 Bearer Token
|
||
|
||
### keys.txt
|
||
每行一個 AES 金鑰，用於 NFC 卡片加密。
|
||
|
||
### urls.txt
|
||
每行一個 URL，前三行為系統保留，從第四行開始可編輯。
|
||
|
||
## 🔧 手動測試
|
||
|
||
訪問 `http://localhost:5000/manual_test` 進行手動測試：
|
||
- 快速 SDM 設定
|
||
- NDEF 操作
|
||
- 變更 AES 金鑰
|
||
- 讀取 UID
|
||
- 自定義指令執行
|
||
- 手動 CMAC 認證
|
||
- 手動 API 驗證
|
||
|
||
## 🌐 API 整合
|
||
|
||
### 支援的 API 端點
|
||
|
||
#### 生產 API
|
||
- **端點**：`POST {API_URL}/nfc/insertForProduction`
|
||
- **用途**：新增生產的 NFC 卡片資料
|
||
- **認證**：Bearer Token
|
||
- **資料格式**：JSON
|
||
|
||
#### 檢驗 API
|
||
- **端點**：`POST {API_URL}/nfc/verifyForProduction`
|
||
- **用途**：檢驗現有 NFC 卡片
|
||
- **認證**：Bearer Token
|
||
- **資料格式**：JSON
|
||
|
||
#### 遠端認證 API
|
||
- **端點**：`GET https://verify.contree.app/verify`
|
||
- **用途**：線上 CMAC 認證
|
||
- **認證**：無需認證
|
||
- **回應格式**：JSON
|
||
|
||
### API 回應範例
|
||
|
||
#### 成功回應
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Operation completed successfully",
|
||
"timestamp": "2025-01-24T12:52:18Z"
|
||
}
|
||
```
|
||
|
||
#### 錯誤回應
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "Error description",
|
||
"error_code": "ERROR_CODE"
|
||
}
|
||
```
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常見問題
|
||
1. **讀卡機無法連接**：檢查 uFR 讀卡機是否正確連接
|
||
2. **權限錯誤**：確保執行檔有執行權限
|
||
3. **依賴缺失**：執行 `pip install -r requirements.txt`
|
||
4. **WebSocket 連接問題**：檢查防火牆設定，確保 5000 端口開放
|
||
5. **API 認證失敗**：檢查 API Token 是否正確設定
|
||
6. **本地認證失敗**：檢查 keys.txt 中的金鑰是否正確
|
||
7. **遠端認證失敗**：檢查網路連接和遠端認證服務狀態
|
||
8. **USB 權限問題**：重新載入 udev 規則
|
||
```bash
|
||
sudo udevadm control --reload-rules
|
||
sudo udevadm trigger
|
||
```
|
||
9. **systemd 服務問題**：檢查服務狀態和日誌
|
||
```bash
|
||
sudo systemctl status NFCapp.service
|
||
sudo journalctl -u NFCapp.service -f
|
||
```
|
||
|
||
### 日誌查看
|
||
應用程式會即時顯示執行日誌，包含顏色標示和詳細錯誤訊息。
|
||
|
||
### 功能特色
|
||
- **即時輸出**：WebSocket 即時顯示執行過程
|
||
- **顏色標示**：支援 ANSI 顏色代碼顯示
|
||
- **自動重連**：WebSocket 自動重連機制
|
||
- **錯誤處理**：完整的錯誤處理和提示
|
||
- **API 整合**：自動 API 認證和資料上傳
|
||
- **雙重認證**：本地 + 遠端認證機制
|
||
- **智能檢測**：自動檢測可用金鑰和錯誤碼
|
||
- **JSON 格式**：標準化的 API 通訊格式
|
||
|
||
## 📞 技術支援
|
||
|
||
如有問題，請檢查：
|
||
1. 硬體連接是否正常
|
||
2. 設定檔是否正確
|
||
3. 執行日誌中的錯誤訊息
|
||
|
||
## 📋 更新日誌
|
||
|
||
### v2.1.0 (2025-01-24)
|
||
- ✅ 改進安裝腳本功能
|
||
- ✅ 新增自動作業系統檢測
|
||
- ✅ 新增 USB 裝置權限自動設定
|
||
- ✅ 新增 systemd 服務自動管理
|
||
- ✅ 新增現有服務自動清理功能
|
||
- ✅ 改進錯誤處理和日誌顯示
|
||
- ✅ 新增多種啟動方式說明
|
||
|
||
### v2.0.0 (2025-01-24)
|
||
- ✅ 新增「生產新SDM」完整流程
|
||
- ✅ 新增「檢驗NFC」功能
|
||
- ✅ 新增「本地CMAC認證」雙重認證
|
||
- ✅ 更新「完整測試NFC」預處理流程
|
||
- ✅ 整合 API 通訊功能
|
||
- ✅ 支援 Bearer Token 認證
|
||
- ✅ 新增 JSON 格式 API 通訊
|
||
- ✅ 改進錯誤處理和狀態檢測
|
||
- ✅ 新增遠端認證整合
|
||
|
||
### v1.0.0 (2024-01)
|
||
- ✅ 基礎 NFC 生產工具
|
||
- ✅ Web 介面
|
||
- ✅ 手動測試功能
|
||
|
||
---
|
||
|
||
**版本**：2.1.0
|
||
**更新日期**：2025年1月24日 |