168 lines
4.2 KiB
Markdown
168 lines
4.2 KiB
Markdown
# 双端依赖安装指南
|
||
|
||
> 本节描述如何让 `gvsds` 主服务器和 `ATestCServer` 等子服务器**共享同一版本**的 `gvsdsdk`。
|
||
|
||
## 1. 版本一致性原则
|
||
|
||
- **同一代码**：双端导入的是**同一份 Python 文件**（物理位置 `D:\SMANAGE\gvsdsdk`）
|
||
- **同一版本**：通过 `pyproject.toml` 中的 `version = "1.0.0"` 锁定
|
||
- **启动校验**：双端启动时调用 `gvsdsdk.check_min_version("1.0.0")`，版本不符会打 WARNING 日志
|
||
- **热重载支持**：直接编辑 `D:\SMANAGE\gvsdsdk` 下的文件即可生效（无需 reinstall）
|
||
|
||
## 2. 三种安装方式
|
||
|
||
### 方式 A：PYTHONPATH 方式（推荐开发用）
|
||
|
||
```bash
|
||
# 启动 gvsds
|
||
cd D:\SMANAGE\gvsds
|
||
set PYTHONPATH=D:\SMANAGE\gvsds;D:\SMANAGE\gvsdsdk
|
||
python manage.py runserver
|
||
|
||
# 启动 ATestCServer
|
||
cd D:\SMANAGE\ATestCServer
|
||
set PYTHONPATH=D:\SMANAGE\ATestCServer;D:\SMANAGE\gvsdsdk
|
||
python manage.py runserver 0.0.0.0:25080
|
||
```
|
||
|
||
`manage.py` 和 `settings.py` 内已自动 `sys.path.append(...)`，无需手动设置。
|
||
|
||
### 方式 B：可编辑 pip 安装（推荐开发用，自动同步）
|
||
|
||
```bash
|
||
# 全局安装一次即可，所有项目共享
|
||
pip install -e D:\SMANAGE\gvsdsdk
|
||
|
||
# 验证
|
||
pip show gvsdsdk
|
||
# Name: gvsdsdk
|
||
# Version: 1.0.0
|
||
# Location: D:\SMANAGE\gvsdsdk
|
||
```
|
||
|
||
### 方式 C：路径式 requirements 固定（推荐生产/部署）
|
||
|
||
`gvsds/requirements.txt`：
|
||
```
|
||
gvsdsdk==1.0.0
|
||
```
|
||
|
||
`ATestCServer/requirements.txt`：
|
||
```
|
||
gvsdsdk==1.0.0
|
||
```
|
||
|
||
部署时 `pip install -r requirements.txt` 会自动从 PyPI 拉取对应版本（或私有源）。
|
||
|
||
## 3. 启动时的版本校验日志
|
||
|
||
**正常启动**（两端版本一致）：
|
||
|
||
```
|
||
gvsds 端:
|
||
[INFO] gvsds.startup: [SDK] 加载: v1.0.0 @ D:\SMANAGE\gvsdsdk
|
||
[INFO] gvsds.startup: [SDK] OK: SDK 1.0.0 >= 1.0.0
|
||
|
||
ATestCServer 端:
|
||
[INFO] apps: [SDK] 加载: v1.0.0 @ D:\SMANAGE\gvsdsdk
|
||
[INFO] apps: [SDK] OK: SDK 1.0.0 >= 1.0.0
|
||
```
|
||
|
||
**版本不一致**（双端版本不同）：
|
||
|
||
```
|
||
[WARN] gvsds.startup: [SDK] 版本不符！FAIL: SDK 0.9.0 < 1.0.0 (required)。双端 gvsdsdk 版本必须一致！
|
||
```
|
||
|
||
## 4. CLI 验证工具
|
||
|
||
```bash
|
||
# 默认：显示简要信息
|
||
python -m gvsdsdk
|
||
|
||
# 仅版本号（适合脚本中调用）
|
||
python -m gvsdsdk --version
|
||
# 1.0.0
|
||
|
||
# 详细信息
|
||
python -m gvsdsdk --info
|
||
# GVS-DSDK Version Information:
|
||
# Version : 1.0.0
|
||
# Major : 1
|
||
# Minor : 0
|
||
# Patch : 0
|
||
# Prerelease :
|
||
# Location : D:\SMANAGE\gvsdsdk
|
||
# Python : 3.12.0
|
||
# Platform : Windows-10-...
|
||
# Machine : AMD64
|
||
|
||
# 最低版本检查（CI 友好）
|
||
python -m gvsdsdk --check 1.0.0
|
||
# OK: SDK 1.0.0 >= 1.0.0 (返回 0)
|
||
|
||
python -m gvsdsdk --check 2.0.0
|
||
# FAIL: SDK 1.0.0 < 2.0.0 (required) (返回 1)
|
||
|
||
# 列出所有公开符号
|
||
python -m gvsdsdk --symbols
|
||
|
||
# 测试连通性
|
||
python -m gvsdsdk --ping
|
||
# Pong — SDK 1.0.0 ready at D:\SMANAGE\gvsdsdk
|
||
# 23 symbols available (lazy)
|
||
```
|
||
|
||
## 5. 升级 SDK 版本
|
||
|
||
当需要发布新版本时：
|
||
|
||
1. **修改 `D:\SMANAGE\gvsdsdk\__init__.py`**：
|
||
```python
|
||
VERSION_MAJOR = 1
|
||
VERSION_MINOR = 1 # 升级
|
||
VERSION_PATCH = 0
|
||
```
|
||
|
||
2. **修改 `D:\SMANAGE\gvsdsdk\pyproject.toml`**：
|
||
```toml
|
||
[project]
|
||
version = "1.1.0"
|
||
```
|
||
|
||
3. **同步更新双端 `requirements.txt`**：
|
||
```
|
||
gvsdsdk==1.1.0
|
||
```
|
||
|
||
4. **同步更新双端最低版本常量**：
|
||
- `gvsds/settings.py:17` → `_REQUIRED_GVSDSDK = '1.1.0'`
|
||
- `ATestCServer/apps/sub_server/apps.py:12` → `REQUIRED_GVSDSDK_VERSION = '1.1.0'`
|
||
|
||
5. **重启双端** → 启动日志会报告新版本
|
||
|
||
## 6. 常见问题
|
||
|
||
| 现象 | 原因 | 解决 |
|
||
|---|---|---|
|
||
| `ImportError: No module named 'gvsdsdk'` | PYTHONPATH 未设置 | 安装 SDK 或加入路径 |
|
||
| `WARNING [SDK] 版本不符` | 双端版本不一致 | 升级较低端 |
|
||
| `WARNING [SDK] gvsdsdk 未安装` | 子服务器 PYTHONPATH 漏配 | 检查 `manage.py:5` |
|
||
| 编辑 SDK 后无变化 | 字节码缓存 | 删除 `__pycache__/` |
|
||
|
||
## 7. 跨平台路径
|
||
|
||
`pyproject.toml` 路径引用应使用 `file:///` 协议：
|
||
|
||
```toml
|
||
gvsdsdk @ file:///D:/SMANAGE/gvsdsdk ; sys_platform == "win32"
|
||
gvsdsdk @ file:///opt/gvsdsdk ; sys_platform == "linux"
|
||
gvsdsdk @ file:///usr/local/gvsdsdk ; sys_platform == "darwin"
|
||
```
|
||
|
||
或在 CI 中使用环境变量：
|
||
|
||
```bash
|
||
pip install -e "$GVS_SDK_PATH"
|
||
```
|