完善服务器部署与生产安全配置

This commit is contained in:
Scout开发者 committed 2026-08-31 00:06:06 +08:00
1 parent d82fd7a28d
commit 4bf2a20efa
17 files changed
+890 -31

No files matched your search

+9
View File
@@ -0,0 +1,9 @@
# Go build context
.git
.gitignore
data
frontend/node_modules
frontend/dist
*.log
*.pkg
*.exe
+2
View File
@@ -2,3 +2,5 @@
*.exe *.exe
*.pkg *.pkg
*.log *.log
deploy/scout.env
*.secret
+64 -30
View File
@@ -1,12 +1,16 @@
package main package main
import ( import (
"context"
"errors"
"log" "log"
"net/http" "net/http"
"os" "os"
"os/signal"
"path/filepath" "path/filepath"
"time" "syscall"
"scout/internal/config"
"scout/internal/httpapi" "scout/internal/httpapi"
"scout/internal/notify" "scout/internal/notify"
"scout/internal/registry" "scout/internal/registry"
@@ -14,47 +18,77 @@ import (
) )
func main() { func main() {
address := envOr("SCOUT_ADDR", ":8080")
dataDir := envOr("SCOUT_DATA_DIR", "data")
token := os.Getenv("SCOUT_DEVELOPER_TOKEN")
logger := log.Default() logger := log.Default()
store, err := registry.New(dataDir) cfg, err := config.Load()
if err != nil { if err != nil {
logger.Fatal(err) logger.Fatal(err)
} }
userStore, err := users.New(filepath.Join(dataDir, "users.json"))
store, err := registry.New(cfg.DataDir)
if err != nil { if err != nil {
logger.Fatal(err) logger.Fatal(err)
} }
if adminEmail := os.Getenv("SCOUT_ADMIN_EMAIL"); adminEmail != "" { userStore, err := users.New(filepath.Join(cfg.DataDir, "users.json"))
if _, err := userStore.EnsureAdmin(adminEmail, os.Getenv("SCOUT_ADMIN_NAME"), os.Getenv("SCOUT_ADMIN_PASSWORD")); err != nil { if err != nil {
logger.Fatal(err) logger.Fatal(err)
} }
} if cfg.AdminEmail != "" {
server := &httpapi.Server{ if _, err := userStore.EnsureAdmin(cfg.AdminEmail, cfg.AdminName, cfg.AdminPassword); err != nil {
Registry: store,
DeveloperToken: token,
MaxUploadBytes: 512 << 20,
Users: userStore,
Mailer: notify.NewFromEnv(logger),
SessionDuration: 24 * time.Hour,
Logger: logger,
}
logger.Printf("Scout 包服务端正在监听 %s,数据目录为 %s", address, dataDir)
if token == "" {
logger.Printf("未配置 SCOUT_DEVELOPER_TOKEN,上传需要开发者账户或管理员账户")
}
if os.Getenv("SCOUT_SMTP_HOST") == "" {
logger.Printf("未配置 SMTP,邮箱通知将只记录日志")
}
if err := http.ListenAndServe(address, server.Handler()); err != nil {
logger.Fatal(err) logger.Fatal(err)
} }
} }
func envOr(name, fallback string) string { api := &httpapi.Server{
if value := os.Getenv(name); value != "" { Registry: store,
return value 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,
}
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,邮箱通知将只记录日志")
}
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
} }
+30
View File
@@ -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
}
+23
View File
@@ -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"]
+11
View File
@@ -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}"
+36
View File
@@ -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:
+13
View File
@@ -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
+47
View File
@@ -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;
}
}
+22
View File
@@ -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 <noreply@example.com>
SCOUT_SMTP_TLS=false
+24
View File
@@ -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
+2 -1
View File
@@ -1,6 +1,6 @@
import { computed, ref } from 'vue' 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' const sessionKey = 'scout-session'
export function useHome() { export function useHome() {
@@ -311,3 +311,4 @@ export function useHome() {
stopNotifications, stopNotifications,
} }
} }
+222
View File
@@ -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
}
+58
View File
@@ -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 <noreply@example.com>")
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 默认配置错误")
}
}
+166
View File
@@ -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
}
+52
View File
@@ -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)
}
}
+109
View File
@@ -256,3 +256,112 @@ go test -race ./...
Set-Location .\frontend Set-Location .\frontend
npm.cmd run build 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. 如升级异常,停止新版本并恢复旧二进制或旧镜像,再恢复数据备份。
当前会话保存在内存中,服务端重启后已有登录会话会失效,客户端需要重新登录;用户和包数据不会因此丢失。