基于Python-SDK的FISCO BCOS區塊鏈HelloWorld模板，提供了簡單的問候語設置和查詢功能。本項目采用現代Python開發實踐，包含完整的配置管理、測試框架和項目結構。

快速開始

倉庫地址：git clone https://gitee.com/atanycosts/python-fisco-template.git

前置要求

• Python 3.7+
• FISCO BCOS節點（2.0或3.0版本）
• Git

1. 環境準備

創建虛擬環境（推薦）

# Windows
rmdir /s /q .venv
python -m venv .venv
.venv\Scripts\activate# Linux/macOS
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate

安裝項目依賴

pip install -r requirements.txt

2. SDK初始化

重要： 如果你重新下載了python-sdk或首次使用，需要進行以下初始化步驟：

2.1 創建SDK配置文件

# 下載sdk(在根目錄下)
git clone https://gitee.com/FISCO-BCOS/python-sdk
# 進入SDK目錄
cd python-sdk# Windows
Copy-Item "client_config.py.template" "client_config.py"# Linux
cp client_config.py.template client_config.py

2.2 安裝SDK依賴

# 在python-sdk目錄下執行
pip install -r requirements.txt

2.3 返回項目目錄

cd ../python-fisco-template

3. 配置環境變量

復制環境變量模板文件：

# Windows，如果存在.env就不用管這一步
Copy-Item ".env.example" ".env"# Linux
cp .env.example .env

編輯 .env 文件，配置你的區塊鏈網絡參數（詳見下方配置說明）。

4. 運行測試

項目提供了完整的測試套件，支持多種運行方式：

# 運行所有測試
pytest test/ -v# 運行特定測試
pytest test/test_blockchain_main.py::test_set_greeting -v# 運行連接測試
pytest test/test_blockchain_main.py::test_blockchain_connection -v# 直接運行Python文件（傳統方式）
python test/test_blockchain_main.py

如果看到類似以下輸出，說明配置成功：

2025-01-XX XX:XX:XX.XXX | INFO | 區塊鏈配置初始化完成，連接節點: your-node-ip:20200
2025-01-XX XX:XX:XX.XXX | INFO | 合約ABI加載成功: resources/abi/HelloWorld.abi
2025-01-XX XX:XX:XX.XXX | SUCCESS | 上鏈成功！交易哈希: 0x...

項目結構

python_fisco_template/
├── .env                              # 環境變量配置文件
├── .gitignore                        # Git忽略文件
├── LICENSE                           # 開源許可證
├── README.md                         # 項目說明文檔
├── requirements.txt                  # Python依賴包列表
├── pytest.ini                       # pytest測試配置
├── pyproject.toml                    # 現代Python項目配置
├── app/                              # 應用核心代碼
│   ├── config/
│   │   ├── __init__.py
│   │   └── blockchain_config.py      # 區塊鏈配置管理類
│   └── services/
│       ├── __init__.py
│       └── blockchain_service.py     # 區塊鏈服務實現
├── bin/                              # 證書和賬戶文件
│   ├── accounts/
│   │   └── pemtest.pem               # 測試賬戶私鑰文件
│   ├── ca.crt                        # CA根證書
│   ├── sdk.crt                       # SDK客戶端證書
│   ├── sdk.key                       # SDK客戶端私鑰
│   └── logs/                         # SDK運行日志目錄
├── logs/                             # 應用日志目錄
│   └── blockchain_test.log           # 測試運行日志
├── python-sdk/                       # FISCO BCOS Python SDK
│   └── ...                           # SDK相關文件
├── resources/                        # 資源文件目錄
│   ├── __init__.py
│   ├── abi/                          # 智能合約ABI文件
│   │   ├── __init__.py
│   │   └── HelloWorld.abi            # HelloWorld合約ABI
│   ├── bin/                          # 智能合約編譯文件
│   │   ├── __init__.py
│   │   └── ecc/                      # ECDSA編譯輸出
│   └── contracts/                    # 智能合約源碼
│       └── HelloWorld.sol            # HelloWorld合約源碼
└── test/                             # 測試文件目錄└── test_blockchain_main.py       # 主要測試腳本

我遇到的問題解決

1. ModuleNotFoundError: No module named ‘client_config’

問題原因： SDK目錄下缺少 client_config.py 文件

解決方案:

cd ../python-sdk
# Windows PowerShell
Copy-Item "client_config.py.template" "client_config.py"
# Linux/macOS
cp client_config.py.template client_config.py

問題: ModuleNotFoundError: No module named 'attrdict'

解決方案:

cd ../python-sdk
pip install -r requirements.txt

2. 連接問題

問題: 無法連接到FISCO BCOS節點

解決方案:

• 檢查 .env 文件中的 BLOCKCHAIN_CHANNEL_HOST 和 BLOCKCHAIN_CHANNEL_PORT
• 確認節點正在運行：ps aux | grep fisco
• 驗證防火墻設置，確保端口20200可訪問
• 檢查證書文件路徑和權限

3. 證書問題

問題: SSL證書驗證失敗

解決方案:

# 檢查證書文件是否存在
ls -la bin/ca.crt bin/sdk.crt bin/sdk.key# 驗證證書有效性
openssl x509 -in bin/sdk.crt -text -noout

• 確保證書文件存在且路徑正確
• 檢查證書是否過期
• 驗證CA證書與節點證書匹配

4. 合約調用失敗

問題: 合約方法調用返回錯誤

解決方案:

• 檢查 BLOCKCHAIN_CONTRACT_ADDRESS 是否為有效的已部署合約地址
• 驗證ABI文件與合約匹配：cat resources/abi/HelloWorld.abi
• 檢查合約方法參數類型和數量

5. 測試運行問題

問題: pytest運行失敗或找不到測試

解決方案:

# 檢查pytest配置
pytest --collect-only# 運行特定測試
pytest test/test_blockchain_main.py::test_set_greeting -v# 檢查Python路徑
python -c "import sys; print('\n'.join(sys.path))"

6. 日志問題

問題: 日志輸出異常或無法寫入

解決方案:

• 確保 logs 目錄存在且有寫入權限
• 檢查 loguru 配置是否正確
• 驗證日志級別設置

7. 環境變量問題

問題: 配置未生效

解決方案:

# 檢查環境變量是否加載
from app.config.blockchain_config import blockchain_config
print(blockchain_config.dict())

• 確保 .env 文件在項目根目錄
• 檢查變量名前綴是否為 BLOCKCHAIN_
• 驗證 python-dotenv 是否正確安裝