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:
106
README.md
106
README.md
@@ -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` 文件将域名指向云服务器 IP。SSH 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.
|
||||
|
||||
Reference in New Issue
Block a user