imnotnoahhh/AI-Proxy-Worker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9a971aa646e129d3bd509aeed6f9e88b3cb004f0
AI-Proxy-Worker/docs/Installation.en.md
Noah Qin 9a971aa646 "🎉 Initial release: AI Proxy Worker v1.0"
2025-08-17 19:59:10 +08:00

7.1 KiB
Raw Blame History

Installation Guide

🌍 Language / 语言

🇺🇸 English | 🇨🇳 中文

This guide provides detailed instructions on how to install the AI Proxy Worker development and deployment environment on different operating systems.

📋 System Requirements

Minimum Requirements

  • Node.js: 18.x or higher
  • npm: 9.x or higher
  • Git: 2.x or higher
  • Cloudflare Account: Free account is sufficient

Recommended Configuration

  • Node.js: 20.x LTS
  • Operating System: Windows 10+, macOS 12+, Ubuntu 20.04+
  • Memory: 4GB+ (for development)

🖥️ Windows Installation

Method 1: Using Official Node.js Installer (Recommended)

1. Download and Install Node.js

  1. Visit Node.js official website
  2. Download LTS version (recommended 20.x)
  3. Run the .msi installer
  4. Keep all default options during installation
  5. Ensure "Add to PATH" option is checked

2. Verify Installation

Open Command Prompt (CMD) or PowerShell:

# Check Node.js version
node --version
# Should display something like: v20.10.0

# Check npm version
npm --version
# Should display something like: 10.2.3

3. Install Git

  1. Visit Git official website
  2. Download Windows version
  3. Run installer with default settings
  4. Verify installation: 
    git --version
# Should display something like: git version 2.43.0

Method 2: Using Package Managers

Using Chocolatey

  1. Open PowerShell as Administrator
  2. Install Chocolatey: 
    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
  3. Install dependencies: 
    choco install nodejs git -y

Using Scoop

# Install Scoop
iwr -useb get.scoop.sh | iex

# Install dependencies
scoop install nodejs git

Method 3: Using WSL2 (Recommended for Developers)

  1. Enable WSL2: 
    # Run as Administrator
wsl --install
  2. Install Ubuntu: 
    wsl --install -d Ubuntu
  3. Follow Linux installation steps in WSL2

🍎 macOS Installation

Method 1: Using Homebrew (Strongly Recommended)

1. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Dependencies

# Install Node.js (includes npm)
brew install node

# Install Git
brew install git

# Verify installation
node --version && npm --version && git --version

Method 2: Using Official Installers

1. Install Node.js

  1. Visit Node.js official website
  2. Download macOS version of LTS release
  3. Run the .pkg installer
  4. Follow installation wizard

2. Install Git

# Git is usually pre-installed, check version
git --version

# If not installed, download official installer
# or use Xcode Command Line Tools
xcode-select --install

Method 3: Using MacPorts

# After installing MacPorts
sudo port install nodejs20 +universal
sudo port install git

🐧 Linux Installation

Ubuntu/Debian

Using apt (Recommended)

# Update package list
sudo apt update

# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Git
sudo apt install git -y

# Verify installation
node --version && npm --version && git --version

Using snap

sudo snap install node --classic
sudo apt install git -y

CentOS/RHEL/Fedora

Using dnf/yum

# Fedora
sudo dnf install nodejs npm git -y

# CentOS/RHEL (requires EPEL)
sudo yum install epel-release -y
sudo yum install nodejs npm git -y

Using NodeSource

# Install Node.js 20.x
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install nodejs git -y

Arch Linux

sudo pacman -S nodejs npm git

🔧 Install Wrangler CLI

After installing Node.js, globally install Cloudflare Wrangler:

# Globally install Wrangler
npm install -g wrangler

# Verify installation
wrangler --version
# Should display something like: ⛅️ wrangler 3.15.0

Common Issues Resolution

Permission Issues (Linux/macOS)

# If encountering permission errors, configure npm global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall Wrangler
npm install -g wrangler

Windows Execution Policy Issues

# If encountering execution policy errors
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

📦 Get Project Code

Method 1: Git Clone (Recommended)

# Clone project
git clone https://github.com/qinfuyao/AI-Proxy-Worker.git

# Enter project directory
cd ai-proxy-worker

# View project structure
ls -la

Method 2: Download ZIP

  1. Visit project GitHub page
  2. Click green "Code" button
  3. Select "Download ZIP"
  4. Extract to local directory
  5. Open terminal and navigate to project directory

✅ Verify Installation

Run the following commands to verify all dependencies are correctly installed:

# Check Node.js
node --version
# ✅ Should display v18.0.0 or higher

# Check npm
npm --version
# ✅ Should display 9.0.0 or higher

# Check Git
git --version
# ✅ Should display git version 2.x.x

# Check Wrangler
wrangler --version
# ✅ Should display wrangler 3.x.x

# Check project files
ls worker.js wrangler.toml
# ✅ Should show these two files exist

🚀 Next Steps

After installation, you can:

  1. Configure deployment environment - Set up Cloudflare account and keys
  2. Quick deployment - Deploy to production in 5 minutes
  3. Local development - Set up local development environment

🔧 Troubleshooting

Common Installation Issues

Node.js Version Too Old

# Uninstall old version
sudo apt remove nodejs npm  # Ubuntu
brew uninstall node        # macOS

# Reinstall latest version following steps above

npm Permission Issues

# Linux/macOS solution
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Wrangler Installation Failed

# Clear npm cache
npm cache clean --force

# Reinstall
npm install -g wrangler

Network Issues (China Users)

# Use Taobao mirror
npm config set registry https://registry.npmmirror.com/

# Reinstall
npm install -g wrangler

Get Help

If you encounter installation issues:

  1. Check Troubleshooting Guide
  2. Search GitHub Issues
  3. Ask questions in Discussions
  4. Check Cloudflare Workers Documentation

Installation Complete? 👉 Start Deployment