ipfs-server（IPFS 服务器）

IPFS Server Operations

You are an IPFS server administrator. You help users run IPFS nodes, manage content, publish data, and operate gateway services. This skill handles full node operations including content publishing and network configuration.

For read-only IPFS queries and content exploration, use the ipfs-client skill.

Installation (macOS)

# Homebrew (recommended)
brew install ipfs

# Or download binary from dist.ipfs.tech
curl -O https://dist.ipfs.tech/kubo/v0.24.0/kubo_v0.24.0_darwin-amd64.tar.gz
tar -xzf kubo_v0.24.0_darwin-amd64.tar.gz
sudo ./kubo/install.sh

Node Initialization

First-time setup:

# Initialize repository
ipfs init

# Show peer ID
ipfs id

# Configure for low-resource usage (optional)
ipfs config profile apply lowpower

Basic configuration:

# Allow gateway on all interfaces (for local network access)
ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

# Configure API (keep localhost for security)
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001

# Set storage limit
ipfs config Datastore.StorageMax 10GB

Starting and Stopping

Start IPFS daemon:

ipfs daemon &> ipfs.log 2>&1 &

Check daemon status:

ipfs swarm peers | wc -l  # Connected peer count
ipfs repo stat            # Repository statistics

Stop daemon:

pkill ipfs

Content Management

Adding Content

Add files and directories:

# Add single file
ipfs add myfile.txt
# Returns: added QmHash myfile.txt

# Add directory recursively  
ipfs add -r ./my-directory/

# Add and only show final hash
ipfs add -Q myfile.txt

# Add with custom name
ipfs add --wrap-with-directory myfile.txt

Add from stdin:

echo "Hello IPFS" | ipfs add
cat largefile.json | ipfs add --pin=false  # Don't pin immediately

Pinning Management

Pin content (prevent garbage collection):

ipfs pin add QmHash
ipfs pin add -r QmHash  # Recursively pin directory

# List pinned content
ipfs pin ls --type=recursive
ipfs pin ls --type=direct

# Unpin content
ipfs pin rm QmHash

Remote pinning services:

# Configure remote pinning (Pinata, Web3.Storage, etc.)
ipfs pin remote service add pinata https://api.pinata.cloud/psa YOUR_JWT

# Pin to remote service
ipfs pin remote add --service=pinata --name="my-content" QmHash

# List remote pins
ipfs pin remote ls --service=pinata

Garbage Collection

Clean up unpinned content:

# Show what would be collected
ipfs repo gc --dry-run

# Run garbage collection
ipfs repo gc

# Check repo size before/after
ipfs repo stat

Publishing and IPNS

IPNS Publishing

Publish content to IPNS:

# Publish to default key
ipfs name publish QmHash

# Create and use custom key
ipfs key gen --type=ed25519 my-site
ipfs name publish --key=my-site QmHash

# List published records
ipfs name pubsub subs

IPNS with custom domains:

# Create DNS TXT record: _dnslink.example.com = "dnslink=/ipns/k51qzi5uqu5d..."
# Then resolve via:
ipfs name resolve /ipns/example.com

Content Updates

Update IPNS record:

# Publish new version
ipfs add -r ./updated-site/
ipfs name publish --key=my-site QmNewHash

Network Configuration

Swarm Management

Peer operations:

# List connected peers
ipfs swarm peers

# Connect to specific peer
ipfs swarm connect /ip4/104.131.131.82/tcp/4001/p2p/QmPeerID

# Disconnect peer
ipfs swarm disconnect /ip4/104.131.131.82/tcp/4001/p2p/QmPeerID

Address configuration:

# Show current addresses
ipfs config Addresses

# Add custom swarm address
ipfs config --json Addresses.Swarm '["/ip4/0.0.0.0/tcp/4001", "/ip6/::/tcp/4001"]'

Bootstrap Nodes

Manage bootstrap peers:

# List bootstrap nodes
ipfs bootstrap list

# Add custom bootstrap node
ipfs bootstrap add /ip4/104.131.131.82/tcp/4001/p2p/QmBootstrapPeer

# Remove all bootstrap nodes (private network)
ipfs bootstrap rm --all

Gateway Operations

Local Gateway

Configure gateway:

# Basic gateway configuration
ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080

# Public gateway (be careful!)
ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080

# Enable directory listing
ipfs config --json Gateway.PublicGateways '{
  "localhost": {
    "Paths": ["/ipfs", "/ipns"],
    "UseSubdomains": false
  }
}'

Access patterns:

# Via path
http://localhost:8080/ipfs/QmHash

# Via subdomain (if configured)
http://QmHash.ipfs.localhost:8080

Reverse Proxy Setup

Nginx configuration example:

server {
    listen 80;
    server_name gateway.example.com;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Advanced Configuration

Performance Tuning

High-performance settings:

# Apply server profile
ipfs config profile apply server

# Increase connection limits
ipfs config Swarm.ConnMgr.HighWater 2000
ipfs config Swarm.ConnMgr.LowWater 1000

# Adjust bitswap settings
ipfs config --json Bitswap.MaxOutstandingBytesPerPeer 1048576

Private Networks

Create private IPFS network:

# Generate swarm key
echo -e "/key/swarm/psk/1.0.0/\
/base16/\
$(tr -dc 'a-f0-9' < /dev/urandom | head -c64)" > ~/.ipfs/swarm.key

# ⚠️ SECURITY: This swarm key is your network's access control credential. 
# Anyone with this file can join your private network. Protect it accordingly.

# Remove all bootstrap nodes
ipfs bootstrap rm --all

# Start daemon (will only connect to nodes with same key)
ipfs daemon

Storage Configuration

Configure datastore:

# Set storage limits
ipfs config Datastore.StorageMax 100GB
ipfs config Datastore.GCPeriod "1h"

# Enable flatfs for better performance
ipfs config --json Datastore.Spec '{
  "mounts": [
    {
      "child": {"type": "flatfs", "path": "blocks", "shardFunc": "/repo/flatfs/shard/v1/next-to-last/2"},
      "mountpoint": "/blocks",
      "prefix": "flatfs.datastore",
      "type": "mount"
    }
  ],
  "type": "mount"
}'

Monitoring and Maintenance

Health Checks

Basic health monitoring:

# Check daemon status
ipfs stats bw          # Bandwidth usage
ipfs stats repo        # Repository stats  
ipfs diag sys          # System information
ipfs log level debug   # Enable debug logging

Connection monitoring:

# Monitor peer connections
while true; do
  echo "$(date): $(ipfs swarm peers | wc -l) peers"
  sleep 60
done

Log Management

Configure logging:

# Set log levels
ipfs log level bitswap info
ipfs log level dht warn

# Tail logs
ipfs log tail

Security Considerations

API access:

• Keep API on localhost (127.0.0.1:5001) unless in trusted network
• Use firewall rules to restrict API access
• Consider authentication proxy for multi-user setups

Gateway security:

• Public gateways can consume significant bandwidth
• Implement rate limiting and caching
• Monitor for abuse and unauthorized content

Content policy:

• IPFS is censorship-resistant - content removal is complex
• Implement content filtering at gateway level if needed
• Consider legal implications of operating public infrastructure

Troubleshooting

Connection issues:

• Check firewall allows ports 4001 (swarm) and 8080 (gateway)
• Verify bootstrap nodes are reachable
• Try different swarm addresses

Performance problems:

• Run garbage collection: ipfs repo gc
• Check available disk space and datastore limits
• Monitor bandwidth usage: ipfs stats bw
• Consider applying performance profiles

Content not accessible:

• Verify content is pinned: ipfs pin ls
• Check if providers exist: ipfs dht findprovs QmHash
• Try republishing IPNS records

Related skills: /ipfs-client (read-only queries), /eth-readonly (blockchain integration)