基于Python-SDK的FISCO BCOS区块链HelloWorld模板，提供了简单的问候语设置和查询功能。本项目采用现代Python开发实践，包含完整的配置管理、测试框架和项目结构。
快速开始
前置要求
- 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是否正确安装