From 4bf2a20efaa3e2fbd96d0e9b07c1f771ca94066c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Scout=E5=BC=80=E5=8F=91=E8=80=85?= Date: Mon, 31 Aug 2026 00:06:06 +0800 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=9C=8D=E5=8A=A1=E5=99=A8?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E4=B8=8E=E7=94=9F=E4=BA=A7=E5=AE=89=E5=85=A8?= =?UTF-8?q?=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .dockerignore | 9 ++ .gitignore | 2 + cmd/scout-server/main.go | 88 ++++++++---- deploy/Caddyfile | 30 ++++ deploy/Dockerfile | 23 ++++ deploy/backup.sh | 11 ++ deploy/docker-compose.yml | 36 +++++ deploy/frontend.Dockerfile | 13 ++ deploy/nginx.conf | 47 +++++++ deploy/scout.env.example | 22 +++ deploy/scout.service | 24 ++++ frontend/src/views/Home/Home.js | 3 +- internal/config/config.go | 222 ++++++++++++++++++++++++++++++ internal/config/config_test.go | 58 ++++++++ internal/httpapi/security.go | 166 ++++++++++++++++++++++ internal/httpapi/security_test.go | 52 +++++++ 使用说明.md | 109 +++++++++++++++ 17 files changed, 887 insertions(+), 28 deletions(-) create mode 100644 .dockerignore create mode 100644 deploy/Caddyfile create mode 100644 deploy/Dockerfile create mode 100644 deploy/backup.sh create mode 100644 deploy/docker-compose.yml create mode 100644 deploy/frontend.Dockerfile create mode 100644 deploy/nginx.conf create mode 100644 deploy/scout.env.example create mode 100644 deploy/scout.service create mode 100644 internal/config/config.go create mode 100644 internal/config/config_test.go create mode 100644 internal/httpapi/security.go create mode 100644 internal/httpapi/security_test.go diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..21703b3 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,9 @@ +# Go build context +.git +.gitignore +data +frontend/node_modules +frontend/dist +*.log +*.pkg +*.exe diff --git a/.gitignore b/.gitignore index 90c7d8a..b871997 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ *.exe *.pkg *.log +deploy/scout.env +*.secret diff --git a/cmd/scout-server/main.go b/cmd/scout-server/main.go index e04d347..ceb3c60 100644 --- a/cmd/scout-server/main.go +++ b/cmd/scout-server/main.go @@ -1,12 +1,16 @@ package main import ( + "context" + "errors" "log" "net/http" "os" + "os/signal" "path/filepath" - "time" + "syscall" + "scout/internal/config" "scout/internal/httpapi" "scout/internal/notify" "scout/internal/registry" @@ -14,47 +18,77 @@ import ( ) func main() { - address := envOr("SCOUT_ADDR", ":8080") - dataDir := envOr("SCOUT_DATA_DIR", "data") - token := os.Getenv("SCOUT_DEVELOPER_TOKEN") logger := log.Default() - store, err := registry.New(dataDir) + cfg, err := config.Load() if err != nil { logger.Fatal(err) } - userStore, err := users.New(filepath.Join(dataDir, "users.json")) + + store, err := registry.New(cfg.DataDir) if err != nil { logger.Fatal(err) } - if adminEmail := os.Getenv("SCOUT_ADMIN_EMAIL"); adminEmail != "" { - if _, err := userStore.EnsureAdmin(adminEmail, os.Getenv("SCOUT_ADMIN_NAME"), os.Getenv("SCOUT_ADMIN_PASSWORD")); err != nil { + userStore, err := users.New(filepath.Join(cfg.DataDir, "users.json")) + if err != nil { + logger.Fatal(err) + } + if cfg.AdminEmail != "" { + if _, err := userStore.EnsureAdmin(cfg.AdminEmail, cfg.AdminName, cfg.AdminPassword); err != nil { logger.Fatal(err) } } - server := &httpapi.Server{ - Registry: store, - DeveloperToken: token, - MaxUploadBytes: 512 << 20, - Users: userStore, - Mailer: notify.NewFromEnv(logger), - SessionDuration: 24 * time.Hour, - Logger: logger, + + api := &httpapi.Server{ + Registry: store, + DeveloperToken: cfg.DeveloperToken, + AllowLegacyToken: cfg.AllowLegacyToken, + MaxUploadBytes: cfg.MaxUploadBytes, + Users: userStore, + Mailer: notify.NewFromEnv(logger), + SessionDuration: cfg.SessionDuration, + AllowedOrigins: cfg.AllowedOrigins, + AllowedHosts: cfg.AllowedHosts, + ForceHTTPS: cfg.ForceHTTPS, + TrustProxy: cfg.TrustProxy, + RateLimitPerMinute: cfg.RateLimitPerMinute, + Logger: logger, } - logger.Printf("Scout 包服务端正在监听 %s,数据目录为 %s", address, dataDir) - if token == "" { - logger.Printf("未配置 SCOUT_DEVELOPER_TOKEN,上传需要开发者账户或管理员账户") + server := &http.Server{ + Addr: cfg.Address, + Handler: api.Handler(), + ReadHeaderTimeout: cfg.ReadHeaderTimeout, + ReadTimeout: cfg.ReadTimeout, + WriteTimeout: cfg.WriteTimeout, + IdleTimeout: cfg.IdleTimeout, + } + + logger.Printf("Scout 包服务端正在监听 %s,数据目录为 %s,运行环境为 %s", cfg.Address, cfg.DataDir, cfg.Environment) + if cfg.DeveloperToken == "" || !cfg.AllowLegacyToken { + logger.Printf("兼容开发者令牌未启用,上传需要开发者账户或管理员账户") } if os.Getenv("SCOUT_SMTP_HOST") == "" { logger.Printf("未配置 SMTP,邮箱通知将只记录日志") } - if err := http.ListenAndServe(address, server.Handler()); err != nil { - logger.Fatal(err) - } -} -func envOr(name, fallback string) string { - if value := os.Getenv(name); value != "" { - return value + serverErrors := make(chan error, 1) + go func() { + serverErrors <- server.ListenAndServe() + }() + + shutdownSignal := make(chan os.Signal, 1) + signal.Notify(shutdownSignal, os.Interrupt, syscall.SIGTERM) + select { + case err := <-serverErrors: + if !errors.Is(err, http.ErrServerClosed) { + logger.Fatal(err) + } + case signal := <-shutdownSignal: + logger.Printf("收到 %s,开始优雅停止服务", signal) + ctx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout) + defer cancel() + if err := server.Shutdown(ctx); err != nil { + logger.Printf("优雅停止失败,强制关闭服务: %v", err) + _ = server.Close() + } } - return fallback } diff --git a/deploy/Caddyfile b/deploy/Caddyfile new file mode 100644 index 0000000..dc5dd56 --- /dev/null +++ b/deploy/Caddyfile @@ -0,0 +1,30 @@ +http://packages.example.com { + encode gzip + + handle /api/v1/updates/stream { + reverse_proxy scout:8080 { + flush_interval -1 + header_up Host {host} + header_up X-Forwarded-Proto {http.request.header.X-Forwarded-Proto} + } + } + + handle /api/* { + request_body { + max_size 512MB + } + reverse_proxy scout:8080 { + header_up Host {host} + header_up X-Forwarded-Proto {http.request.header.X-Forwarded-Proto} + } + } + + handle /healthz { + reverse_proxy scout:8080 + } + + root * /srv/scout/frontend/dist + try_files {path} /index.html + file_server +} + diff --git a/deploy/Dockerfile b/deploy/Dockerfile new file mode 100644 index 0000000..c88102c --- /dev/null +++ b/deploy/Dockerfile @@ -0,0 +1,23 @@ +# syntax=docker/dockerfile:1 + +FROM golang:1.26-alpine AS build +WORKDIR /src +COPY go.mod ./ +COPY cmd ./cmd +COPY internal ./internal +COPY pkg ./pkg +RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath -ldflags="-s -w" -o /out/scout-server ./cmd/scout-server + +FROM alpine:3.22 +RUN addgroup -S scout && adduser -S -G scout scout \ + && apk add --no-cache ca-certificates tzdata +WORKDIR /app +COPY --from=build /out/scout-server /app/scout-server +RUN mkdir -p /var/lib/scout && chown -R scout:scout /var/lib/scout /app +USER scout +ENV SCOUT_ENV=production \ + SCOUT_ADDR=:8080 \ + SCOUT_DATA_DIR=/var/lib/scout +EXPOSE 8080 +VOLUME ["/var/lib/scout"] +ENTRYPOINT ["/app/scout-server"] diff --git a/deploy/backup.sh b/deploy/backup.sh new file mode 100644 index 0000000..4439ecc --- /dev/null +++ b/deploy/backup.sh @@ -0,0 +1,11 @@ +#!/bin/sh +set -eu + +source_dir="${SCOUT_DATA_DIR:-/var/lib/scout}" +backup_dir="${SCOUT_BACKUP_DIR:-/var/backups/scout}" +timestamp="$(date -u +%Y%m%dT%H%M%SZ)" +archive="${backup_dir}/scout-${timestamp}.tar.gz" + +mkdir -p "${backup_dir}" +tar -czf "${archive}" -C "${source_dir}" . +printf '备份完成: %s\n' "${archive}" diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml new file mode 100644 index 0000000..910843f --- /dev/null +++ b/deploy/docker-compose.yml @@ -0,0 +1,36 @@ +services: + scout: + build: + context: .. + dockerfile: deploy/Dockerfile + restart: unless-stopped + env_file: + - ./scout.env + environment: + SCOUT_ENV: production + SCOUT_ADDR: :8080 + SCOUT_DATA_DIR: /var/lib/scout + volumes: + - scout-data:/var/lib/scout + expose: + - "8080" + healthcheck: + test: ["CMD", "wget", "--spider", "--quiet", "http://127.0.0.1:8080/healthz"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s + + web: + build: + context: .. + dockerfile: deploy/frontend.Dockerfile + restart: unless-stopped + depends_on: + scout: + condition: service_healthy + ports: + - "127.0.0.1:8081:80" + +volumes: + scout-data: diff --git a/deploy/frontend.Dockerfile b/deploy/frontend.Dockerfile new file mode 100644 index 0000000..0de9531 --- /dev/null +++ b/deploy/frontend.Dockerfile @@ -0,0 +1,13 @@ +# syntax=docker/dockerfile:1 + +FROM node:24-alpine AS build +WORKDIR /src/frontend +COPY frontend/package*.json ./ +RUN npm ci +COPY frontend ./ +RUN npm run build + +FROM nginx:1.29-alpine +COPY --from=build /src/frontend/dist /usr/share/nginx/html +COPY deploy/nginx.conf /etc/nginx/conf.d/default.conf +EXPOSE 80 diff --git a/deploy/nginx.conf b/deploy/nginx.conf new file mode 100644 index 0000000..19b8c0e --- /dev/null +++ b/deploy/nginx.conf @@ -0,0 +1,47 @@ +map $http_x_forwarded_proto $scout_forwarded_proto { + default $http_x_forwarded_proto; + "" $scheme; +} +server { + listen 80; + server_name _; + + root /usr/share/nginx/html; + index index.html; + + client_max_body_size 512m; + + location /api/v1/updates/stream { + proxy_pass http://scout:8080; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scout_forwarded_proto; + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 1h; + } + + location /api/ { + proxy_pass http://scout:8080; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scout_forwarded_proto; + proxy_request_buffering off; + proxy_read_timeout 10m; + } + + location = /healthz { + proxy_pass http://scout:8080; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scout_forwarded_proto; + } + + location / { + try_files $uri $uri/ /index.html; + } +} + diff --git a/deploy/scout.env.example b/deploy/scout.env.example new file mode 100644 index 0000000..1212ed3 --- /dev/null +++ b/deploy/scout.env.example @@ -0,0 +1,22 @@ +# 复制为 /etc/scout/scout.env,并替换所有占位符。 +SCOUT_ENV=production +SCOUT_ADDR=127.0.0.1:8080 +SCOUT_DATA_DIR=/var/lib/scout +SCOUT_PUBLIC_URL=https://packages.example.com +SCOUT_ALLOWED_ORIGINS=https://packages.example.com +SCOUT_ALLOWED_HOSTS=packages.example.com +SCOUT_FORCE_HTTPS=true +SCOUT_TRUST_PROXY=true +SCOUT_ALLOW_LEGACY_TOKEN=false +SCOUT_RATE_LIMIT_PER_MINUTE=120 +SCOUT_SESSION_DURATION=24h +SCOUT_MAX_UPLOAD_BYTES=512MB +SCOUT_ADMIN_EMAIL=admin@example.com +SCOUT_ADMIN_NAME=系统管理员 +SCOUT_ADMIN_PASSWORD=请替换为随机强密码 +SCOUT_SMTP_HOST=smtp.example.com +SCOUT_SMTP_PORT=587 +SCOUT_SMTP_USERNAME=请从密钥管理系统注入 +SCOUT_SMTP_PASSWORD=请从密钥管理系统注入 +SCOUT_SMTP_FROM=Scout +SCOUT_SMTP_TLS=false diff --git a/deploy/scout.service b/deploy/scout.service new file mode 100644 index 0000000..277d410 --- /dev/null +++ b/deploy/scout.service @@ -0,0 +1,24 @@ +[Unit] +Description=Scout 轻量化包管理服务 +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=scout +Group=scout +WorkingDirectory=/opt/scout +EnvironmentFile=/etc/scout/scout.env +ExecStart=/opt/scout/scout-server +Restart=on-failure +RestartSec=5s + +# 服务端自身只监听内网地址,公网 TLS 和域名由反向代理处理。 +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +ReadWritePaths=/var/lib/scout + +[Install] +WantedBy=multi-user.target diff --git a/frontend/src/views/Home/Home.js b/frontend/src/views/Home/Home.js index 2fe111d..07f98ed 100644 --- a/frontend/src/views/Home/Home.js +++ b/frontend/src/views/Home/Home.js @@ -1,6 +1,6 @@ import { computed, ref } from 'vue' -const defaultApi = import.meta.env.VITE_API_BASE || 'http://127.0.0.1:8080' +const defaultApi = import.meta.env.VITE_API_BASE || (['5173', '5174'].includes(window.location.port) ? 'http://127.0.0.1:8080' : window.location.origin) const sessionKey = 'scout-session' export function useHome() { @@ -311,3 +311,4 @@ export function useHome() { stopNotifications, } } + diff --git a/internal/config/config.go b/internal/config/config.go new file mode 100644 index 0000000..dc0b1b3 --- /dev/null +++ b/internal/config/config.go @@ -0,0 +1,222 @@ +package config + +import ( + "errors" + "fmt" + "net/url" + "os" + "strconv" + "strings" + "time" +) + +type Config struct { + Environment string + Address string + DataDir string + PublicURL string + AdminEmail string + AdminName string + AdminPassword string + DeveloperToken string + AllowLegacyToken bool + AllowedOrigins []string + AllowedHosts []string + ForceHTTPS bool + TrustProxy bool + SessionDuration time.Duration + MaxUploadBytes int64 + RateLimitPerMinute int + ReadHeaderTimeout time.Duration + ReadTimeout time.Duration + WriteTimeout time.Duration + IdleTimeout time.Duration + ShutdownTimeout time.Duration + LogLevel string +} + +func Load() (Config, error) { + environment := strings.ToLower(strings.TrimSpace(envOr("SCOUT_ENV", "development"))) + if environment == "" { + environment = "development" + } + if environment != "development" && environment != "test" && environment != "production" { + return Config{}, errors.New("SCOUT_ENV 只能是 development、test 或 production") + } + + sessionDuration, err := durationEnv("SCOUT_SESSION_DURATION", 24*time.Hour) + if err != nil { + return Config{}, err + } + maxUploadBytes, err := bytesEnv("SCOUT_MAX_UPLOAD_BYTES", 512<<20) + if err != nil { + return Config{}, err + } + rateLimit, err := intEnv("SCOUT_RATE_LIMIT_PER_MINUTE", 120) + if err != nil || rateLimit < 0 { + return Config{}, errors.New("SCOUT_RATE_LIMIT_PER_MINUTE 必须是大于等于 0 的整数") + } + + cfg := Config{ + Environment: environment, + Address: envOr("SCOUT_ADDR", ":8080"), + DataDir: envOr("SCOUT_DATA_DIR", "data"), + PublicURL: strings.TrimRight(strings.TrimSpace(os.Getenv("SCOUT_PUBLIC_URL")), "/"), + AdminEmail: strings.TrimSpace(os.Getenv("SCOUT_ADMIN_EMAIL")), + AdminName: strings.TrimSpace(os.Getenv("SCOUT_ADMIN_NAME")), + AdminPassword: os.Getenv("SCOUT_ADMIN_PASSWORD"), + DeveloperToken: os.Getenv("SCOUT_DEVELOPER_TOKEN"), + AllowedOrigins: csvEnv("SCOUT_ALLOWED_ORIGINS"), + AllowedHosts: csvEnv("SCOUT_ALLOWED_HOSTS"), + ForceHTTPS: boolEnv("SCOUT_FORCE_HTTPS", environment == "production"), + TrustProxy: boolEnv("SCOUT_TRUST_PROXY", false), + SessionDuration: sessionDuration, + MaxUploadBytes: maxUploadBytes, + RateLimitPerMinute: rateLimit, + ReadHeaderTimeout: durationDefault("SCOUT_READ_HEADER_TIMEOUT", 10*time.Second), + ReadTimeout: durationDefault("SCOUT_READ_TIMEOUT", 60*time.Second), + WriteTimeout: durationDefault("SCOUT_WRITE_TIMEOUT", 10*time.Minute), + IdleTimeout: durationDefault("SCOUT_IDLE_TIMEOUT", 2*time.Minute), + ShutdownTimeout: durationDefault("SCOUT_SHUTDOWN_TIMEOUT", 15*time.Second), + LogLevel: strings.ToLower(envOr("SCOUT_LOG_LEVEL", "info")), + } + cfg.AllowLegacyToken = boolEnv("SCOUT_ALLOW_LEGACY_TOKEN", environment != "production") + + if err := cfg.validate(); err != nil { + return Config{}, err + } + return cfg, nil +} + +func (cfg Config) validate() error { + if strings.TrimSpace(cfg.Address) == "" || strings.TrimSpace(cfg.DataDir) == "" { + return errors.New("SCOUT_ADDR 和 SCOUT_DATA_DIR 不能为空") + } + if cfg.SessionDuration <= 0 || cfg.MaxUploadBytes <= 0 { + return errors.New("会话时长和上传大小必须大于 0") + } + if cfg.LogLevel != "debug" && cfg.LogLevel != "info" && cfg.LogLevel != "warn" && cfg.LogLevel != "error" { + return errors.New("SCOUT_LOG_LEVEL 只能是 debug、info、warn 或 error") + } + if cfg.PublicURL != "" { + parsed, err := url.Parse(cfg.PublicURL) + if err != nil || parsed.Host == "" || (parsed.Scheme != "http" && parsed.Scheme != "https") { + return errors.New("SCOUT_PUBLIC_URL 必须是完整的 HTTP 或 HTTPS 地址") + } + if cfg.Environment == "production" && parsed.Scheme != "https" { + return errors.New("生产环境的 SCOUT_PUBLIC_URL 必须使用 HTTPS") + } + } + if cfg.Environment != "production" { + return nil + } + if cfg.AdminEmail == "" || cfg.AdminPassword == "" { + return errors.New("生产环境必须配置 SCOUT_ADMIN_EMAIL 和 SCOUT_ADMIN_PASSWORD") + } + if cfg.AdminPassword == "Admin-Test-123" { + return errors.New("生产环境不能使用本地测试管理员密码") + } + if cfg.DeveloperToken != "" && !cfg.AllowLegacyToken { + return errors.New("生产环境默认禁止兼容开发者令牌;如确需启用,请设置 SCOUT_ALLOW_LEGACY_TOKEN=true") + } + if len(cfg.AllowedOrigins) == 0 { + return errors.New("生产环境必须配置 SCOUT_ALLOWED_ORIGINS") + } + if len(cfg.AllowedHosts) == 0 { + return errors.New("生产环境必须配置 SCOUT_ALLOWED_HOSTS") + } + if cfg.PublicURL == "" { + return errors.New("生产环境必须配置 SCOUT_PUBLIC_URL") + } + if os.Getenv("SCOUT_SMTP_HOST") == "" || os.Getenv("SCOUT_SMTP_FROM") == "" { + return errors.New("生产环境必须配置 SCOUT_SMTP_HOST 和 SCOUT_SMTP_FROM") + } + return nil +} + +func envOr(name, fallback string) string { + if value := os.Getenv(name); value != "" { + return value + } + return fallback +} + +func csvEnv(name string) []string { + values := make([]string, 0) + for _, value := range strings.Split(os.Getenv(name), ",") { + value = strings.TrimSpace(value) + if value != "" { + values = append(values, strings.TrimRight(value, "/")) + } + } + return values +} + +func boolEnv(name string, fallback bool) bool { + value := strings.TrimSpace(os.Getenv(name)) + if value == "" { + return fallback + } + parsed, err := strconv.ParseBool(value) + if err != nil { + return fallback + } + return parsed +} + +func intEnv(name string, fallback int) (int, error) { + value := strings.TrimSpace(os.Getenv(name)) + if value == "" { + return fallback, nil + } + parsed, err := strconv.Atoi(value) + if err != nil { + return 0, fmt.Errorf("%s 必须是整数", name) + } + return parsed, nil +} + +func durationEnv(name string, fallback time.Duration) (time.Duration, error) { + value := strings.TrimSpace(os.Getenv(name)) + if value == "" { + return fallback, nil + } + parsed, err := time.ParseDuration(value) + if err != nil || parsed <= 0 { + return 0, fmt.Errorf("%s 必须是大于 0 的时间长度,例如 24h 或 30s", name) + } + return parsed, nil +} + +func durationDefault(name string, fallback time.Duration) time.Duration { + value, err := durationEnv(name, fallback) + if err != nil { + return fallback + } + return value +} + +func bytesEnv(name string, fallback int64) (int64, error) { + value := strings.TrimSpace(os.Getenv(name)) + if value == "" { + return fallback, nil + } + multiplier := int64(1) + upper := strings.ToUpper(value) + switch { + case strings.HasSuffix(upper, "KB"): + multiplier = 1 << 10 + value = strings.TrimSpace(value[:len(value)-2]) + case strings.HasSuffix(upper, "MB"): + multiplier = 1 << 20 + value = strings.TrimSpace(value[:len(value)-2]) + case strings.HasSuffix(upper, "GB"): + multiplier = 1 << 30 + value = strings.TrimSpace(value[:len(value)-2]) + } + number, err := strconv.ParseInt(value, 10, 64) + if err != nil || number <= 0 { + return 0, fmt.Errorf("%s 必须是正整数或带 KB、MB、GB 后缀的大小", name) + } + return number * multiplier, nil +} diff --git a/internal/config/config_test.go b/internal/config/config_test.go new file mode 100644 index 0000000..0f86e2d --- /dev/null +++ b/internal/config/config_test.go @@ -0,0 +1,58 @@ +package config + +import ( + "testing" + "time" +) + +func TestLoadDevelopmentDefaults(t *testing.T) { + for _, name := range []string{ + "SCOUT_ENV", "SCOUT_ADDR", "SCOUT_DATA_DIR", "SCOUT_PUBLIC_URL", + "SCOUT_ADMIN_EMAIL", "SCOUT_ADMIN_NAME", "SCOUT_ADMIN_PASSWORD", + "SCOUT_DEVELOPER_TOKEN", "SCOUT_ALLOWED_ORIGINS", "SCOUT_ALLOWED_HOSTS", + "SCOUT_FORCE_HTTPS", "SCOUT_TRUST_PROXY", "SCOUT_SESSION_DURATION", + "SCOUT_MAX_UPLOAD_BYTES", "SCOUT_RATE_LIMIT_PER_MINUTE", "SCOUT_LOG_LEVEL", + "SCOUT_SMTP_HOST", "SCOUT_SMTP_FROM", + } { + t.Setenv(name, "") + } + cfg, err := Load() + if err != nil { + t.Fatal(err) + } + if cfg.Environment != "development" || cfg.SessionDuration != 24*time.Hour || cfg.MaxUploadBytes != 512<<20 { + t.Fatalf("开发环境默认配置错误: %+v", cfg) + } + if !cfg.AllowLegacyToken { + t.Fatal("开发环境默认应兼容旧版开发者令牌") + } +} + +func TestLoadProductionRequiresDeploymentSettings(t *testing.T) { + t.Setenv("SCOUT_ENV", "production") + if _, err := Load(); err == nil { + t.Fatal("生产环境缺少安全配置时不应启动") + } +} + +func TestLoadProductionWithDeploymentSettings(t *testing.T) { + t.Setenv("SCOUT_ENV", "production") + t.Setenv("SCOUT_ADMIN_EMAIL", "admin@example.com") + t.Setenv("SCOUT_ADMIN_PASSWORD", "a-strong-production-password") + t.Setenv("SCOUT_PUBLIC_URL", "https://packages.example.com") + t.Setenv("SCOUT_ALLOWED_ORIGINS", "https://packages.example.com") + t.Setenv("SCOUT_ALLOWED_HOSTS", "packages.example.com") + t.Setenv("SCOUT_SMTP_HOST", "smtp.example.com") + t.Setenv("SCOUT_SMTP_FROM", "Scout ") + t.Setenv("SCOUT_ALLOW_LEGACY_TOKEN", "false") + cfg, err := Load() + if err != nil { + t.Fatal(err) + } + if cfg.AllowLegacyToken { + t.Fatal("生产环境默认不应启用兼容令牌") + } + if !cfg.ForceHTTPS || cfg.TrustProxy { + t.Fatal("生产环境 HTTPS 默认配置错误") + } +} diff --git a/internal/httpapi/security.go b/internal/httpapi/security.go new file mode 100644 index 0000000..cccca96 --- /dev/null +++ b/internal/httpapi/security.go @@ -0,0 +1,166 @@ +package httpapi + +import ( + "net" + "net/http" + "strings" + "sync" + "time" +) + +type rateLimitEntry struct { + windowStart time.Time + count int +} + +type rateLimiter struct { + mu sync.Mutex + limit int + entries map[string]rateLimitEntry +} + +func (s *Server) hostGuard(next http.Handler) http.Handler { + if len(s.AllowedHosts) == 0 && !s.ForceHTTPS { + return next + } + return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) { + if len(s.AllowedHosts) > 0 && !hostAllowed(request.Host, s.AllowedHosts) { + writeError(writer, http.StatusMisdirectedRequest, "请求域名不在允许列表中") + return + } + if s.ForceHTTPS && requestURLScheme(request, s.TrustProxy) != "https" { + writeError(writer, http.StatusBadRequest, "当前服务要求使用 HTTPS") + return + } + next.ServeHTTP(writer, request) + }) +} + +func (s *Server) rateLimit(next http.Handler) http.Handler { + if s.RateLimitPerMinute <= 0 { + return next + } + limiter := &rateLimiter{limit: s.RateLimitPerMinute, entries: make(map[string]rateLimitEntry)} + return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) { + key := clientAddress(request, s.TrustProxy) + now := time.Now() + if !limiter.allow(key, now) { + writer.Header().Set("Retry-After", "60") + writeError(writer, http.StatusTooManyRequests, "请求过于频繁,请稍后再试") + return + } + next.ServeHTTP(writer, request) + }) +} + +func (limiter *rateLimiter) allow(key string, now time.Time) bool { + limiter.mu.Lock() + defer limiter.mu.Unlock() + entry, ok := limiter.entries[key] + if !ok || now.Sub(entry.windowStart) >= time.Minute { + limiter.entries[key] = rateLimitEntry{windowStart: now, count: 1} + if len(limiter.entries) > 10000 { + for address, current := range limiter.entries { + if now.Sub(current.windowStart) >= time.Minute { + delete(limiter.entries, address) + } + } + } + return true + } + if entry.count >= limiter.limit { + return false + } + entry.count++ + limiter.entries[key] = entry + return true +} + +func (s *Server) cors(next http.Handler) http.Handler { + return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) { + origin := strings.TrimSpace(request.Header.Get("Origin")) + allowed := origin == "" + if len(s.AllowedOrigins) == 0 { + if origin != "" { + writer.Header().Set("Access-Control-Allow-Origin", "*") + } + allowed = true + } else { + for _, configured := range s.AllowedOrigins { + if origin == configured { + writer.Header().Set("Access-Control-Allow-Origin", origin) + writer.Header().Add("Vary", "Origin") + allowed = true + break + } + } + } + if origin != "" && !allowed { + writeError(writer, http.StatusForbidden, "访问来源不在允许列表中") + return + } + writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Developer-Token") + writer.Header().Set("Access-Control-Allow-Methods", "GET, POST, PATCH, OPTIONS") + writer.Header().Set("Access-Control-Max-Age", "600") + if request.Method == http.MethodOptions { + writer.WriteHeader(http.StatusNoContent) + return + } + next.ServeHTTP(writer, request) + }) +} + +func securityHeaders(next http.Handler) http.Handler { + return http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) { + writer.Header().Set("X-Content-Type-Options", "nosniff") + writer.Header().Set("X-Frame-Options", "DENY") + writer.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin") + writer.Header().Set("Permissions-Policy", "camera=(), microphone=(), geolocation=()") + writer.Header().Set("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'") + next.ServeHTTP(writer, request) + }) +} + +func hostAllowed(value string, allowed []string) bool { + host := strings.ToLower(strings.TrimSpace(value)) + if parsed, _, err := net.SplitHostPort(host); err == nil { + host = parsed + } + host = strings.TrimSuffix(host, ".") + for _, candidate := range allowed { + candidate = strings.ToLower(strings.TrimSpace(candidate)) + candidate = strings.TrimSuffix(candidate, ".") + if candidate == host || candidate == "*" { + return true + } + if strings.HasPrefix(candidate, "*.") && strings.HasSuffix(host, candidate[1:]) { + return true + } + } + return false +} + +func requestURLScheme(request *http.Request, trustProxy bool) string { + if trustProxy { + if value := strings.ToLower(strings.TrimSpace(request.Header.Get("X-Forwarded-Proto"))); value != "" { + return value + } + } + if request.TLS != nil { + return "https" + } + return "http" +} + +func clientAddress(request *http.Request, trustProxy bool) string { + if trustProxy { + if forwarded := strings.TrimSpace(strings.Split(request.Header.Get("X-Forwarded-For"), ",")[0]); forwarded != "" { + return forwarded + } + } + value := strings.TrimSpace(request.RemoteAddr) + if host, _, err := net.SplitHostPort(value); err == nil { + return host + } + return value +} diff --git a/internal/httpapi/security_test.go b/internal/httpapi/security_test.go new file mode 100644 index 0000000..4cab86c --- /dev/null +++ b/internal/httpapi/security_test.go @@ -0,0 +1,52 @@ +package httpapi + +import ( + "net/http" + "net/http/httptest" + "testing" +) + +func TestSecurityHeadersAndCORS(t *testing.T) { + server := (&Server{AllowedOrigins: []string{"https://packages.example.com"}}).Handler() + request := httptest.NewRequest(http.MethodGet, "/healthz", nil) + request.Header.Set("Origin", "https://packages.example.com") + response := httptest.NewRecorder() + server.ServeHTTP(response, request) + if response.Code != http.StatusOK { + t.Fatalf("健康检查状态错误: %d", response.Code) + } + if response.Header().Get("Access-Control-Allow-Origin") != "https://packages.example.com" { + t.Fatal("允许来源响应头错误") + } + if response.Header().Get("X-Content-Type-Options") != "nosniff" { + t.Fatal("安全响应头缺失") + } +} + +func TestHostGuardRejectsUnknownHost(t *testing.T) { + server := (&Server{AllowedHosts: []string{"packages.example.com"}}).Handler() + request := httptest.NewRequest(http.MethodGet, "http://unknown.example.com/healthz", nil) + response := httptest.NewRecorder() + server.ServeHTTP(response, request) + if response.Code != http.StatusMisdirectedRequest { + t.Fatalf("未知主机状态错误: %d", response.Code) + } +} + +func TestRateLimit(t *testing.T) { + server := (&Server{RateLimitPerMinute: 1}).Handler() + first := httptest.NewRequest(http.MethodGet, "/healthz", nil) + first.RemoteAddr = "192.0.2.10:1234" + firstResponse := httptest.NewRecorder() + server.ServeHTTP(firstResponse, first) + if firstResponse.Code != http.StatusOK { + t.Fatalf("首次请求状态错误: %d", firstResponse.Code) + } + second := httptest.NewRequest(http.MethodGet, "/healthz", nil) + second.RemoteAddr = "192.0.2.10:5678" + secondResponse := httptest.NewRecorder() + server.ServeHTTP(secondResponse, second) + if secondResponse.Code != http.StatusTooManyRequests { + t.Fatalf("限流状态错误: %d", secondResponse.Code) + } +} diff --git a/使用说明.md b/使用说明.md index d46a426..4ebcb8e 100644 --- a/使用说明.md +++ b/使用说明.md @@ -256,3 +256,112 @@ go test -race ./... Set-Location .\frontend npm.cmd run build ``` + +## 服务器部署与反向代理 + +Scout 的服务端可以部署在 Linux 服务器上。推荐让 Scout 只监听内网地址,由现有的 Nginx、Caddy、云负载均衡或其他网关负责公网入口、域名、SSL 证书和 DNS。Scout 不会申请、续期或修改 SSL、DNS,也不会保存域名服务商凭据。 + +### 生产环境配置 + +复制示例配置并写入服务器的密钥管理位置: + +```bash +cp deploy/scout.env.example /etc/scout/scout.env +chmod 600 /etc/scout/scout.env +``` + +必须替换以下占位内容: + +- `SCOUT_PUBLIC_URL`:客户端实际访问的完整地址,例如 `https://packages.example.com`。 +- `SCOUT_ALLOWED_ORIGINS`:允许访问 API 的前端来源,多个来源使用英文逗号分隔。 +- `SCOUT_ALLOWED_HOSTS`:反向代理转发到 Scout 的 Host,多个主机名使用英文逗号分隔。 +- `SCOUT_ADMIN_EMAIL`、`SCOUT_ADMIN_PASSWORD`:生产管理员邮箱和随机强密码。 +- `SCOUT_SMTP_*`:管理员、上传用户和安全认证通知使用的 SMTP 配置。 + +生产环境会拒绝默认测试管理员密码、缺少允许来源、缺少允许主机和缺少 SMTP 发件配置。`SCOUT_ALLOW_LEGACY_TOKEN` 默认关闭;推荐使用开发者账户会话上传,不要在公网长期保留兼容令牌。 + +### Docker Compose + +服务器安装 Docker 和 Compose 后,在项目根目录执行: + +```bash +cp deploy/scout.env.example deploy/scout.env +# 编辑 deploy/scout.env,替换所有生产占位符 + docker compose -f deploy/docker-compose.yml up -d --build +``` + +Compose 会启动 Scout API 和前端静态站点: + +- Scout API 仅在 Compose 网络内提供 `8080` 端口。 +- 前端站点绑定服务器本机 `127.0.0.1:8081`。 +- 包文件和用户数据保存在 Docker 卷 `scout-data` 中。 +- 外部域名入口应转发到 `127.0.0.1:8081`,并把原始 Host、客户端 IP 和 `X-Forwarded-Proto` 传递下来。 + +查看状态和日志: + +```bash +docker compose -f deploy/docker-compose.yml ps +docker compose -f deploy/docker-compose.yml logs -f scout +``` + +### systemd + +不使用 Docker 时,可将编译后的 `scout-server` 放到 `/opt/scout/scout-server`,创建运行用户和数据目录: + +```bash +sudo useradd --system --home /var/lib/scout --shell /usr/sbin/nologin scout +sudo install -d -o scout -g scout /var/lib/scout /etc/scout +sudo install -m 0755 scout-server /opt/scout/scout-server +sudo install -m 0600 deploy/scout.env.example /etc/scout/scout.env +# 编辑 /etc/scout/scout.env 后再执行以下命令 +sudo systemctl daemon-reload +sudo systemctl enable --now scout.service +sudo systemctl status scout.service +``` + +`deploy/scout.service` 已配置自动重启、最小权限、只读系统保护和独立数据目录。停止或升级时使用: + +```bash +sudo systemctl restart scout.service +sudo journalctl -u scout.service -f +``` + +### Nginx 转发要求 + +`deploy/nginx.conf` 是容器内前端站点的参考配置。外部网关需要满足以下要求: + +- `/api/` 转发到 Scout API。 +- `/api/v1/updates/stream` 关闭代理缓冲,并将读取超时设置为至少 1 小时。 +- 上传接口允许的请求体大小不小于 `SCOUT_MAX_UPLOAD_BYTES`。 +- 转发 `Host`、`X-Real-IP`、`X-Forwarded-For` 和 `X-Forwarded-Proto`。 +- 如果 `SCOUT_TRUST_PROXY=true`,只允许可信反向代理访问 Scout,不能让公网客户端直接伪造这些请求头。 +- SSL 证书、证书续期、DNS 解析和域名绑定由外部网关或云服务负责。 + +外部网关终止 HTTPS 后,必须将 `X-Forwarded-Proto: https` 传给 Scout;否则生产配置中的 `SCOUT_FORCE_HTTPS=true` 会拒绝请求。这是协议边界检查,不是 Scout 的证书管理功能。 + +### 健康检查、备份和升级 + +健康检查接口: + +```text +GET /healthz +``` + +返回 `{"status":"ok"}` 只代表进程可以响应。生产监控还应检查反向代理、磁盘空间、SMTP 可用性和实际包下载。 + +备份至少包括整个 `SCOUT_DATA_DIR`,其中包含用户数据、密码哈希、包元数据和包文件: + +```bash +SCOUT_DATA_DIR=/var/lib/scout SCOUT_BACKUP_DIR=/var/backups/scout sh deploy/backup.sh +``` + +升级建议流程: + +1. 先执行备份并确认备份文件可读取。 +2. 在测试环境执行 `go test ./...` 和 `npm run build`。 +3. 构建新镜像或替换二进制文件。 +4. 重启服务并检查 `/healthz`、用户登录、包列表、上传和下载。 +5. 观察日志和磁盘空间后再删除旧版本。 +6. 如升级异常,停止新版本并恢复旧二进制或旧镜像,再恢复数据备份。 + +当前会话保存在内存中,服务端重启后已有登录会话会失效,客户端需要重新登录;用户和包数据不会因此丢失。