docs: update README for CLI tool usage, remove old script

- Rewrite README.md with CLI usage instructions
- Add __main__.py for `python -m jianda_proxy` support
- Clean up unused imports in config.py and test_config.py
- Add pytest dev dependency to pyproject.toml
- Remove lfs-proxy.py (replaced by modular CLI tool)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-28 17:58:19 +08:00
parent 5fcb4596e4
commit 0023b57596
7 changed files with 353 additions and 111 deletions

106
README.md
View File

@@ -1,44 +1,112 @@
# jianda-proxy
本地 HTTP 代理,解决腾讯云对未备案域名拦截导致的 Git LFS 下载失败问题。
HTTP proxy for Gitea LFS -- rewrites Host header to bypass ICP domain blocking.
## 背景
## Background
内网 Gitea 通过反向隧道暴露到腾讯云,客户端通过 `hosts` 文件将域名指向云服务器 IPSSH clone 正常,但 LFS 文件下载走 HTTP 协议,腾讯云检测到域名未备案,基于 Host 头拦截请求返回 302。
Internal Gitea is exposed via a reverse tunnel on a Tencent Cloud server. The client resolves the domain via `hosts` file to the cloud IP. SSH clone works fine, but LFS file downloads go over HTTP. Tencent Cloud detects the unregistered domain from the Host header and blocks the request with a 302 redirect.
本代理将所有发往 `git.zz.com` 的请求的 Host 头改写为 IP 地址,绕过备案拦截。
This proxy rewrites the Host header on all requests to the upstream IP address, bypassing the ICP block.
## 使用方法
### 1. 启动代理
## Installation
```bash
python3 lfs-proxy.py [port]
# Install as a global CLI tool (recommended)
uv tool install .
# Or with pip
pip install .
```
默认监听 `127.0.0.1:13000`,可指定其他端口。
## CLI Commands
### 2. 配置 Git 走代理(只需一次)
### Start the proxy
```bash
# Start as a background daemon (default)
jianda-proxy start
# Run in the foreground (useful for debugging)
jianda-proxy start --foreground
# Override the listen port
jianda-proxy start --port 8080
```
### Stop the proxy
```bash
jianda-proxy stop
```
### Check status
```bash
jianda-proxy status
```
### Manage configuration
```bash
# View all config values
jianda-proxy config list
# Get a specific value
jianda-proxy config get upstream_host
# Set a value
jianda-proxy config set listen_port 8080
# Show config file path
jianda-proxy config path
```
## Configuration
Default values (written to config file on first run):
| Key | Default | Description |
|----------------|------------------|--------------------------------|
| remote_domain | git.zz.com | Domain to intercept |
| upstream_host | 62.234.191.215 | Upstream server IP |
| upstream_port | 3000 | Upstream server port |
| listen_host | 127.0.0.1 | Proxy listen address |
| listen_port | 13000 | Proxy listen port |
Config file location: `~/.config/jianda-proxy/config.ini` (or `%APPDATA%\jianda-proxy\config.ini` on Windows).
## Example Workflow
1. Install and start the proxy:
```bash
jianda-proxy start
```
2. Configure Git to route LFS requests through the proxy (one-time setup):
```bash
git config --global http.http://git.zz.com:3000/.proxy http://127.0.0.1:13000
```
### 3. 正常 clone
3. Clone as usual:
```bash
git clone ssh://git@git.zz.com:2222/Mustapha/lfs-test.git
git clone ssh://git@git.zz.com:2222/your-repo.git
```
## 原理
LFS downloads will be routed through the proxy transparently.
代理同时支持两种模式:
## Running without installation
- **正向代理**:接收 `GET http://git.zz.com:3000/...` 形式的请求,改写 Host 头转发到上游
- **反向代理**:接收 `GET /...` 形式的请求,直接转发到上游并附带 IP Host 头
```bash
# Via uv
uv run python -m jianda_proxy start --foreground
上游地址硬编码为 `62.234.191.215:3000`,可在脚本顶部修改。
# Via python directly
python -m jianda_proxy start --foreground
```
## 根治方案
## Root Cause Fix
在 Gitea 服务端 `app.ini` 中将 `ROOT_URL``http://git.zz.com:3000` 改为 `http://62.234.191.215:3000`,可从根源解决,无需代理。
Setting `ROOT_URL` in Gitea's `app.ini` to the IP address (e.g. `http://62.234.191.215:3000`) eliminates the need for this proxy entirely.