mirror of
https://github.com/KohakuBlueleaf/KohakuHub.git
synced 2026-05-02 18:38:02 -05:00
137 lines
4.1 KiB
Markdown
137 lines
4.1 KiB
Markdown
# Cloudflare Pages Functions
|
|
|
|
This directory contains Cloudflare Pages Functions for routing and proxying requests to the KohakuHub backend API.
|
|
|
|
## How It Works
|
|
|
|
Cloudflare Pages serves the static frontend and uses Functions to proxy API/backend requests to your origin server.
|
|
|
|
**Request Flow:**
|
|
```
|
|
User → Cloudflare Pages (CDN) → Functions (routing) → Your Server (API)
|
|
↓
|
|
Static files served from CDN
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
functions/
|
|
├── _middleware.js # Middleware applied to all requests
|
|
├── _proxy.js # Shared proxy handler
|
|
├── _utils.js # Proxy utilities with Git protocol support
|
|
├── api/[[path]].js # Catch-all for /api/* routes
|
|
├── org/[[path]].js # Organization routes
|
|
├── [[repo]].git/ # Git Smart HTTP protocol
|
|
│ ├── info/
|
|
│ │ ├── refs.js # Service advertisement
|
|
│ │ └── lfs/[[path]].js # Git LFS
|
|
│ ├── git-upload-pack.js # Clone/fetch/pull
|
|
│ ├── git-receive-pack.js # Push
|
|
│ └── HEAD.js # HEAD reference
|
|
├── models/[[namespace]]/[[name]]/resolve/[[path]].js # Model file downloads
|
|
├── datasets/.../resolve/[[path]].js # Dataset file downloads
|
|
├── spaces/.../resolve/[[path]].js # Space file downloads
|
|
└── [[namespace]]/[[name]]/resolve/[[path]].js # Legacy file downloads
|
|
```
|
|
|
|
## Git Protocol Handling
|
|
|
|
**Special Configuration for Git:**
|
|
|
|
Git Smart HTTP requires special handling:
|
|
- ✅ **No caching** - Responses must not be cached
|
|
- ✅ **Preserve headers** - Content-Type must be preserved
|
|
- ✅ **No CORS** - Git clients don't support CORS headers
|
|
|
|
**Implementation in `_utils.js`:**
|
|
```javascript
|
|
if (isGitRequest(pathname)) {
|
|
// Prevent caching (critical!)
|
|
headers.set('Cache-Control', 'no-store, no-cache, must-revalidate');
|
|
headers.set('X-Content-Type-Options', 'nosniff');
|
|
headers.set('X-Accel-Buffering', 'no');
|
|
// NO CORS headers (breaks Git clients)
|
|
}
|
|
```
|
|
|
|
## Routes Configuration
|
|
|
|
**`public/_routes.json`** specifies which paths should be handled by Functions:
|
|
|
|
```json
|
|
{
|
|
"include": [
|
|
"/api/*",
|
|
"/org/*",
|
|
"/*.git/info/refs", // Git service advertisement
|
|
"/*.git/git-upload-pack", // Git clone/fetch/pull
|
|
"/*.git/git-receive-pack", // Git push
|
|
"/*.git/HEAD", // Git HEAD reference
|
|
"/*.git/info/lfs/*", // Git LFS
|
|
"/models/*/*/resolve/*", // File downloads
|
|
...
|
|
]
|
|
}
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Set in Cloudflare Pages dashboard:
|
|
|
|
```bash
|
|
API_BASE_URL=https://api.your-hub.com # Your backend API URL
|
|
```
|
|
|
|
If not set, defaults to `http://hub-api:48888` (Docker internal).
|
|
|
|
## Testing Locally
|
|
|
|
```bash
|
|
# Install Wrangler
|
|
npm install -g wrangler
|
|
|
|
# Test functions locally
|
|
wrangler pages dev dist --compatibility-date=2024-01-01
|
|
|
|
# Test Git clone
|
|
git clone http://localhost:8788/namespace/repo.git
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Functions are automatically deployed with Cloudflare Pages:
|
|
|
|
1. Push to GitHub
|
|
2. Cloudflare Pages builds frontend
|
|
3. Functions deployed from `functions/` directory
|
|
4. Environment variables applied
|
|
|
|
## Troubleshooting
|
|
|
|
**Git clone fails:**
|
|
- Check `_routes.json` includes Git paths
|
|
- Verify `isGitRequest()` detects Git URLs correctly
|
|
- Ensure no caching headers are set
|
|
- Check Cloudflare Page Rules don't interfere
|
|
|
|
**CORS errors:**
|
|
- Git protocol should NOT have CORS headers
|
|
- Browser requests should have CORS headers
|
|
- Check `isGitRequest()` logic
|
|
|
|
**404 errors:**
|
|
- Verify path is in `_routes.json` include list
|
|
- Check function file exists for the route pattern
|
|
- Verify `API_BASE_URL` environment variable
|
|
|
|
## Related Documentation
|
|
|
|
- [docs/Git.md](../docs/Git.md) - Git clone support
|
|
- [docs/cloudflare-git-setup.md](../docs/cloudflare-git-setup.md) - Cloudflare configuration
|
|
- [Cloudflare Pages Functions Docs](https://developers.cloudflare.com/pages/functions/)
|
|
|
|
---
|
|
|
|
**Last Updated:** October 2025
|