基于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 是否正确安装