# python-api-template

**Repository Path**: zhangfaquan/python-api-template

## Basic Information

- **Project Name**: python-api-template
- **Description**: 接口工程模板-python
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 测试指令

```shell
# 运行测试目录下的所有用例
uv run pytest -v

# 运行某个测试文件
uv run pytest test/test_calc.py -v

# 执行单个测试方法
uv run pytest src/test/service/test_user_test_user_service_integration.py::TestUserIntegration::test_insert_user_success -v -s
```

# 查看测试报告

```shell
# 进入 htmlcov 目录
cd htmlcov
# python3 启动服务
uv run python -m http.server 8000
```

# 接口文档

Swagger UI: <http://localhost:8000/docs>
ReDoc: <http://localhost:8000/redoc>

# Redis Cluster 部署（Docker）

基于 Docker Compose 部署 Redis 集群（3 主 3 从），配置文件位于 `docker/redis-cluster/`。

## 部署规格

| 项目     | 值                  |
| ------ | ------------------ |
| 节点数    | 6（3 主 + 3 从）       |
| 密码     | `123456`           |
| 宿主机端口  | `26381` \~ `26386` |
| 集群总线端口 | `36381` \~ `36386` |

## 端口映射

| 容器           | 宿主机端口 | 角色      |
| ------------ | ----- | ------- |
| redis-node-1 | 26381 | Master  |
| redis-node-2 | 26382 | Master  |
| redis-node-3 | 26383 | Master  |
| redis-node-4 | 26384 | Replica |
| redis-node-5 | 26385 | Replica |
| redis-node-6 | 26386 | Replica |

## 部署步骤

```powershell
cd docker\redis-cluster
docker-compose up -d
docker exec redis-node-1 bash /init-cluster.sh
```

每次重启后都需执行

```shell
docker exec redis-node-1 bash /init-cluster.sh
```

<br />

步骤内具体细节说明

```powershell
# 1. 启动 6 个 Redis 容器
cd docker\redis-cluster
docker-compose up -d

# 2. 等待节点就绪（约 5 秒）

# 3. 初始化集群（3主3从）
docker exec redis-node-1 redis-cli --cluster create `
  redis-node-1:6379 redis-node-2:6379 redis-node-3:6379 `
  redis-node-4:6379 redis-node-5:6379 redis-node-6:6379 `
  --cluster-replicas 1 --cluster-yes

# 4. 配置集群节点的 announce 参数（宿主机访问必需）
docker exec redis-node-1 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-1 redis-cli CONFIG SET cluster-announce-port 26381

docker exec redis-node-2 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-2 redis-cli CONFIG SET cluster-announce-port 26382

docker exec redis-node-3 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-3 redis-cli CONFIG SET cluster-announce-port 26383

docker exec redis-node-4 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-4 redis-cli CONFIG SET cluster-announce-port 26384

docker exec redis-node-5 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-5 redis-cli CONFIG SET cluster-announce-port 26385

docker exec redis-node-6 redis-cli CONFIG SET cluster-announce-hostname localhost
docker exec redis-node-6 redis-cli CONFIG SET cluster-announce-port 26386

# 5. 验证集群状态
docker exec redis-node-1 redis-cli cluster info
docker exec redis-node-1 redis-cli cluster nodes
docker exec redis-node-1 redis-cli cluster slots
```

期望输出：

- `cluster_state:ok`
- 16384 slots 全部分配
- 6 个节点已识别
- cluster slots 输出中每个节点显示 `localhost` 和对应端口

## 重要说明

### cluster-announce 配置

部署步骤中的第 4 步设置了 `cluster-announce-hostname` 和 `cluster-announce-port`，这是**宿主机访问集群的必需配置**：

- **目的**：让集群节点向客户端宣告宿主机可访问的地址（`localhost:26381-26386`）
- **原理**：Redis 集群在重定向客户端时使用这些参数，而不是容器内部地址
- **注意**：这些配置是动态设置的，容器重启后会丢失，需要重新执行配置步骤

如果使用 `init-cluster.sh` 脚本，可以一次性完成集群创建和 announce 配置：

```powershell
docker exec redis-node-1 bash /init-cluster.sh
```

该脚本会自动检测集群状态并设置 announce 参数。

### 密码配置

当前配置未启用密码认证。如需启用密码：

1. 在 `redis.conf` 中添加 `requirepass 123456`
2. 在 `docker-compose.yml` 中添加 `--requirepass 123456` 到 command 参数
3. 应用配置中设置对应的 `password: "123456"`

## 停止集群

```powershell
cd docker\redis-cluster
docker-compose down -v
```

> `-v` 会同时删除数据卷，清空持久化数据。如需保留数据，去掉 `-v`。

## 数据存储位置

Redis 数据采用 Docker 命名卷（named volumes）存储，位于 WSL2 虚拟机内部。

### 查看存储位置

```powershell
# 查看所有数据卷
docker volume ls --filter name=redis-cluster

# 查看某个节点数据卷的实际挂载路径
docker volume inspect redis-cluster_redis-node-1-data --format "{{.Mountpoint}}"
```

### 实际存储位置

| 节点     | WSL2 内路径                                                        |
| ------ | --------------------------------------------------------------- |
| node-1 | `/var/lib/docker/volumes/redis-cluster_redis-node-1-data/_data` |
| node-2 | `/var/lib/docker/volumes/redis-cluster_redis-node-2-data/_data` |
| node-3 | `/var/lib/docker/volumes/redis-cluster_redis-node-3-data/_data` |
| node-4 | `/var/lib/docker/volumes/redis-cluster_redis-node-4-data/_data` |
| node-5 | `/var/lib/docker/volumes/redis-cluster_redis-node-5-data/_data` |
| node-6 | `/var/lib/docker/volumes/redis-cluster_redis-node-6-data/_data` |

### Windows 访问方式

在资源管理器地址栏输入以下路径可直接访问 WSL 文件系统：

```
\\wsl$\docker-desktop-data\data\docker\volumes\
```

数据卷目录内包含 Redis 的持久化文件：

- `appendonly.aof` — AOF 持久化文件
- `nodes.conf` — 集群拓扑配置文件
- `dump.rdb` — RDB 快照文件（如开启）

## 应用配置

`src/resources/app_config.yaml` 已预配置集群模式：

```yaml
redis:
  mode: cluster
  password: "123456"
  cluster:
    nodes:
      - host: localhost
        port: 26381
      - host: localhost
        port: 26382
      - host: localhost
        port: 26383
      - host: localhost
        port: 26384
      - host: localhost
        port: 26385
      - host: localhost
        port: 26386
```