docs(proxyman): add setup and debugging guides and link them from readmes
This commit is contained in:
Draculabo committed
1 parent
e9c4f72883
commit
3100db93ed
4 files changed
+404
No files matched your search
@@ -50,6 +50,7 @@
|
||||
- [Quick Start](#-quick-start)
|
||||
- [Tech Stack](#️-tech-stack)
|
||||
- [Development](#-development)
|
||||
- [Debugging Docs](#-debugging-docs)
|
||||
- [FAQ](#-faq)
|
||||
- [Contributing](#-contributing)
|
||||
- [License](#-license)
|
||||
@@ -311,6 +312,15 @@ AntigravityManager/
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Debugging Docs
|
||||
|
||||
If you want to inspect Antigravity or Antigravity Manager traffic with Proxyman, start here:
|
||||
|
||||
- [Proxyman Installation and Basic Setup on Windows](docs/proxyman-install.md)
|
||||
- [Proxyman Debugging Guide for Antigravity and Antigravity Manager](docs/proxyman-debugging.md)
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
<details>
|
||||
|
||||
@@ -50,6 +50,7 @@
|
||||
- [快速开始](#-快速开始)
|
||||
- [技术栈](#️-技术栈)
|
||||
- [开发指南](#-开发指南)
|
||||
- [调试文档](#-调试文档)
|
||||
- [常见问题](#-常见问题)
|
||||
- [贡献指南](#-贡献指南)
|
||||
- [许可证](#-许可证)
|
||||
@@ -310,6 +311,15 @@ AntigravityManager/
|
||||
|
||||
---
|
||||
|
||||
## 🔍 调试文档
|
||||
|
||||
如果你希望用 Proxyman 抓取和排查 Antigravity 或 Antigravity Manager 的流量，请先阅读：
|
||||
|
||||
- [Proxyman Installation and Basic Setup on Windows](docs/proxyman-install.md)
|
||||
- [Proxyman Debugging Guide for Antigravity and Antigravity Manager](docs/proxyman-debugging.md)
|
||||
|
||||
---
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
<details>
|
||||
|
||||
@@ -0,0 +1,244 @@
|
||||
# Proxyman Debugging Guide for Antigravity and Antigravity Manager
|
||||
|
||||
This guide explains how to use Proxyman for two debugging targets:
|
||||
|
||||
1. The installed official `Antigravity` desktop client
|
||||
2. The `Antigravity Manager` development build from this repository
|
||||
|
||||
Before you start, complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
|
||||
## Scope
|
||||
|
||||
Use this guide when you want to:
|
||||
|
||||
- inspect login, quota, project context, or model-list requests from `Antigravity`
|
||||
- inspect OAuth, quota refresh, or proxy traffic from `Antigravity Manager`
|
||||
- compare requests from the official client with requests produced by this project
|
||||
|
||||
## Understand the Two Traffic Paths
|
||||
|
||||
### Official `Antigravity` Client
|
||||
|
||||
`Antigravity` is an Electron application. Its traffic may come from:
|
||||
|
||||
- Chromium or renderer-side requests
|
||||
- Electron or Node-side requests
|
||||
|
||||
### `Antigravity Manager` in This Repository
|
||||
|
||||
This project is also an Electron app, but it additionally includes Node, Undici, and internal proxy flows. You may need to inspect:
|
||||
|
||||
- Electron main-process outbound requests
|
||||
- renderer-side requests
|
||||
- upstream requests emitted by `src/server/`
|
||||
|
||||
## Debug the Installed Official Antigravity Client
|
||||
|
||||
### Recommended Path: Use the Repository Script
|
||||
|
||||
Use the provided script:
|
||||
|
||||
- [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
|
||||
This should be the default path for the installed official client because it already does the following:
|
||||
|
||||
- sets `HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY`
|
||||
- sets `NODE_EXTRA_CA_CERTS`
|
||||
- passes `--proxy-server` and `--proxy-bypass-list`
|
||||
- stops existing `Antigravity` processes so the new environment takes effect
|
||||
|
||||
Typical usage:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
If Proxyman is using a different port:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -Port 9091
|
||||
```
|
||||
|
||||
If you are temporarily debugging TLS failures:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1 -AllowInsecureTls
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- This script targets the installed official `Antigravity` client.
|
||||
- It does not launch this repository's `Antigravity Manager` development build.
|
||||
- Override `-AppPath`, `-CaPath`, `-ProxyHost`, or `-NoProxy` if your local environment differs.
|
||||
|
||||
### Suggested Flow
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Confirm that installation and certificate setup are already complete.
|
||||
3. Confirm the local proxy port, for example `9090`.
|
||||
4. Launch `Antigravity` with the script.
|
||||
5. Trigger a request that is easy to identify, such as:
|
||||
- Google sign-in
|
||||
- model list loading
|
||||
- quota refresh
|
||||
- a generated request or prompt action
|
||||
|
||||
### Why Manual Parameters Are Still Documented
|
||||
|
||||
The script is the recommended default, but the raw parameters are still useful because:
|
||||
|
||||
- contributors may want to understand exactly what the script configures
|
||||
- some people launch from VS Code, another shell, or a custom wrapper
|
||||
- some debugging sessions need a partial override rather than the full script
|
||||
|
||||
### If Windows System Proxy Is Not Enough
|
||||
|
||||
In some environments you may still need to point the system proxy to Proxyman manually. At minimum, verify:
|
||||
|
||||
- HTTP proxy: `127.0.0.1:9090`
|
||||
- HTTPS proxy: `127.0.0.1:9090`
|
||||
- the bypass list is not excluding the domains you want to inspect
|
||||
|
||||
### If You Need Direct Chromium Proxy Arguments
|
||||
|
||||
If system proxy behavior is unreliable, you can launch the installed client with explicit Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
& "C:\Users\<YourUser>\AppData\Local\Programs\Antigravity\Antigravity.exe" `
|
||||
--proxy-server="http://127.0.0.1:9090" `
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Use this as a fallback, not the default path.
|
||||
|
||||
## Debug Antigravity Manager From This Repository
|
||||
|
||||
This project has more layers than the official client. The script above is not the general launcher for this repository's development app.
|
||||
|
||||
### Capture Main-Process, Node, and Internal Proxy Traffic
|
||||
|
||||
Set proxy-related environment variables before starting the app:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
|
||||
# Enable only for temporary TLS debugging
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start
|
||||
```
|
||||
|
||||
This primarily affects:
|
||||
|
||||
- Node HTTP and HTTPS requests
|
||||
- `undici`, `fetch`, and some dependency-driven upstream requests
|
||||
- internal proxy requests forwarded to upstream services
|
||||
|
||||
### Also Capture Electron and Chromium Traffic
|
||||
|
||||
If you want both Node-side and renderer-side traffic, add Chromium proxy arguments:
|
||||
|
||||
```powershell
|
||||
$env:HTTP_PROXY = "http://127.0.0.1:9090"
|
||||
$env:HTTPS_PROXY = "http://127.0.0.1:9090"
|
||||
$env:ALL_PROXY = "http://127.0.0.1:9090"
|
||||
$env:NO_PROXY = "localhost,127.0.0.1,::1"
|
||||
$env:NODE_EXTRA_CA_CERTS = "$env:APPDATA\\Proxyman\\certificate\\certs\\ca.pem"
|
||||
$env:NODE_TLS_REJECT_UNAUTHORIZED = "0"
|
||||
|
||||
npm start -- --proxy-server="http://127.0.0.1:9090" --proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
If your local `npm start` flow does not forward arguments to Electron Forge, use one of these fallback approaches:
|
||||
|
||||
- capture only Node and main-process traffic
|
||||
- wrap the Electron launch in your own PowerShell or VS Code task
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### I Can See Requests but HTTPS Bodies Are Empty
|
||||
|
||||
Check:
|
||||
|
||||
- the Proxyman root certificate is really trusted
|
||||
- `NODE_EXTRA_CA_CERTS` is set when Node-side traffic needs it
|
||||
- `NODE_TLS_REJECT_UNAUTHORIZED=0` is only being used as a temporary debugging override
|
||||
- the target app is not using SSL pinning
|
||||
|
||||
Background setup guide:
|
||||
|
||||
- [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
|
||||
### I Can See Browser Traffic but Not Node or Main-Process Traffic
|
||||
|
||||
Common causes:
|
||||
|
||||
- Node is not using system proxy settings
|
||||
- the HTTP client does not read `HTTP_PROXY`
|
||||
- only the system proxy was configured, but runtime environment variables were not
|
||||
|
||||
### I Cannot See `localhost` Traffic
|
||||
|
||||
Common cause:
|
||||
|
||||
- loopback traffic is bypassing the proxy
|
||||
|
||||
Keep this bypass list in mind when launching Electron:
|
||||
|
||||
```plaintext
|
||||
--proxy-bypass-list="<local>;localhost;127.0.0.1;::1"
|
||||
```
|
||||
|
||||
Adjust it only if your current debugging target requires a different loopback behavior.
|
||||
|
||||
### TLS Still Fails After the Certificate Was Installed
|
||||
|
||||
Common causes:
|
||||
|
||||
- the process started before the certificate was installed and needs a full restart
|
||||
- `ca.cer` was imported but `ca.pem` was not passed to Node when required
|
||||
- a corporate proxy, VPN, or security product is changing network behavior
|
||||
- the target app uses SSL pinning
|
||||
|
||||
## Security Notes
|
||||
|
||||
Keep local debugging settings out of the repository and out of public issue threads.
|
||||
|
||||
- Do not commit your local proxy address, certificate paths, cookies, or OAuth codes.
|
||||
- Do not leave `NODE_TLS_REJECT_UNAUTHORIZED=0` enabled beyond temporary local debugging.
|
||||
- Do not post raw tokens, sessions, or authorization headers in public issues.
|
||||
- Redact logs before sharing them.
|
||||
|
||||
## Minimal Workflows
|
||||
|
||||
### Official Antigravity Client
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open Proxyman.
|
||||
3. Run:
|
||||
|
||||
```powershell
|
||||
powershell -ExecutionPolicy Bypass -File .\scripts\start-antigravity-with-proxyman.ps1
|
||||
```
|
||||
|
||||
4. Trigger login, quota, or model-list traffic.
|
||||
|
||||
### Antigravity Manager in This Repository
|
||||
|
||||
1. Complete [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md).
|
||||
2. Open PowerShell.
|
||||
3. Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NODE_EXTRA_CA_CERTS`.
|
||||
4. Run `npm start`.
|
||||
5. Filter Proxyman traffic by domains such as:
|
||||
- `googleapis.com`
|
||||
- `googleusercontent.com`
|
||||
- the upstream domain you are debugging
|
||||
|
||||
## Related Files
|
||||
|
||||
- Setup guide: [Proxyman Installation and Basic Setup on Windows](./proxyman-install.md)
|
||||
- Official-client launcher: [scripts/start-antigravity-with-proxyman.ps1](../scripts/start-antigravity-with-proxyman.ps1)
|
||||
@@ -0,0 +1,140 @@
|
||||
# Proxyman Installation and Basic Setup on Windows
|
||||
|
||||
This guide covers the Proxyman prerequisites for contributors:
|
||||
|
||||
1. Install Proxyman for Windows
|
||||
2. Trust the Proxyman certificate so HTTPS traffic can be decrypted
|
||||
3. Verify that Proxyman is working before you start debugging Antigravity traffic
|
||||
|
||||
If your goal is to debug the installed Antigravity client or this repository's development build, continue with [Proxyman Debugging Guide](./proxyman-debugging.md).
|
||||
|
||||
## Scope
|
||||
|
||||
This document is intentionally limited to the setup layer. It does not cover Antigravity-specific debugging flows.
|
||||
|
||||
Use it when you need to answer:
|
||||
|
||||
- How do I install Proxyman on Windows?
|
||||
- How do I trust the certificate?
|
||||
- Why can I only see CONNECT requests but not HTTPS bodies?
|
||||
- How do I verify that Proxyman itself is working?
|
||||
|
||||
## Install Proxyman
|
||||
|
||||
Official resources:
|
||||
|
||||
- Download: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Windows product page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
|
||||
Recommended steps:
|
||||
|
||||
1. Install the Windows build from the official download page.
|
||||
2. Launch Proxyman.
|
||||
3. Confirm that Proxyman is listening on a local proxy port.
|
||||
4. This guide uses `9090` as the example port. Replace it with your local port if it differs.
|
||||
|
||||
## Install and Trust the Certificate
|
||||
|
||||
Without the Proxyman root certificate, you will usually only see CONNECT tunnels or TLS handshakes instead of decrypted HTTPS requests.
|
||||
|
||||
Official references:
|
||||
|
||||
- Windows certificate installation: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
|
||||
### Recommended Path: Install Automatically
|
||||
|
||||
In Proxyman, run:
|
||||
|
||||
```plaintext
|
||||
Certificate -> Install Certificate on this Windows...
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
1. Choose `Install & Trust`
|
||||
2. Approve the administrator prompt
|
||||
|
||||
According to the official documentation, Proxyman uses Windows `certutil` to import the root certificate into the trusted store.
|
||||
|
||||
### Prepare a PEM File for Node and Electron
|
||||
|
||||
Some Node.js and Electron traffic needs more than system trust. You may also need to point the runtime at the PEM file:
|
||||
|
||||
```plaintext
|
||||
%APPDATA%\Proxyman\certificate\certs\ca.pem
|
||||
```
|
||||
|
||||
If you only see `ca.cer` and not `ca.pem`, confirm that Proxyman has generated the PEM variant before moving on.
|
||||
|
||||
## Verify That Proxyman Works
|
||||
|
||||
Do this before trying to debug any application-specific flow.
|
||||
|
||||
### Verify Browser Traffic
|
||||
|
||||
1. Open Proxyman.
|
||||
2. Visit any HTTPS page in a browser, for example:
|
||||
|
||||
```plaintext
|
||||
https://httpbin.org/get
|
||||
```
|
||||
|
||||
3. Confirm that the request and response appear in Proxyman.
|
||||
|
||||
### If You Cannot See Any Traffic
|
||||
|
||||
Check these first:
|
||||
|
||||
- Proxyman is actually listening on the expected port
|
||||
- Windows proxy settings are pointing to Proxyman
|
||||
- A VPN, endpoint security agent, or antivirus is not taking over proxy behavior
|
||||
- The certificate is trusted
|
||||
|
||||
If localhost traffic is missing, see:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
The official page includes macOS-specific examples, but the localhost bypass concept is still relevant on Windows.
|
||||
|
||||
## Basic Troubleshooting
|
||||
|
||||
### HTTPS Bodies Are Missing
|
||||
|
||||
Common causes:
|
||||
|
||||
- The Proxyman root certificate is not actually trusted
|
||||
- The target process was already running before the certificate was installed
|
||||
- The application uses SSL pinning
|
||||
|
||||
### Certificate Is Installed but TLS Still Fails
|
||||
|
||||
Common causes:
|
||||
|
||||
- You imported `ca.cer` but did not provide `ca.pem` to the runtime when needed
|
||||
- A corporate proxy, VPN, or security product is overriding the network path
|
||||
- The target application uses SSL pinning
|
||||
|
||||
### Localhost Traffic Is Missing
|
||||
|
||||
Common cause:
|
||||
|
||||
- Local loopback traffic is bypassing the proxy
|
||||
|
||||
Official reference:
|
||||
|
||||
- [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
|
||||
## Next Step
|
||||
|
||||
Once Proxyman is installed, trusted, and verified, continue with:
|
||||
|
||||
- [Proxyman Debugging Guide](./proxyman-debugging.md)
|
||||
|
||||
## References
|
||||
|
||||
- Proxyman download page: [https://proxyman.com/download](https://proxyman.com/download)
|
||||
- Proxyman Windows page: [https://proxyman.com/windows](https://proxyman.com/windows)
|
||||
- Proxyman Windows certificate guide: [https://docs.proxyman.com/proxyman-windows/install-certificate](https://docs.proxyman.com/proxyman-windows/install-certificate)
|
||||
- Proxyman localhost troubleshooting: [https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server](https://docs.proxyman.com/troubleshooting/couldnt-see-any-request-from-localhost-server)
|
||||
- Proxyman SSL troubleshooting: [https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response](https://docs.proxyman.com/troubleshooting/get-ssl-error-from-https-request-and-response)
|
||||
Reference in new issue
Block a user