Environment Variables¶
PixivFE's behavior is controlled by environment variables. Currently, you can only set variables directly in your environment.
An example configuration is provided in .env.example.
Tip
To quickly set up PixivFE, you need to define two required environment variables:
PIXIVFE_TOKEN: Your Pixiv account cookie, which is necessary for accessing Pixiv's Ajax API. Refer to the guide on obtaining the PIXIVFE_TOKEN cookie for details on how to acquire your Pixiv token.PIXIVFE_PORT: The port number on which PixivFE will run, for example,8282.
For basic usage, configure your environment variables as follows:
If you are setting up a development environment, enable the development mode by also setting:
| Text Only | |
|---|---|
PIXIVFE_PORT or PIXIVFE_UNIXSOCKET¶
Required: No
PIXIVFE_PORT: Port to listen on, e.g.,PIXIVFE_PORT=8282.PIXIVFE_UNIXSOCKET: UNIX socket to listen on, e.g.,PIXIVFE_UNIXSOCKET=/tmp/pixivfe.sock.
If neither are provided, PixivFE will listen on port 8282 by default.
PIXIVFE_TOKEN¶
Required: Yes
Your Pixiv account cookie, used by PixivFE for authorization to fully access Pixiv's Ajax API. This variable can contain multiple tokens separated by commas, which is useful for load balancing across multiple Pixiv accounts.
Example:
| Text Only | |
|---|---|
See the Obtaining the PIXIVFE_TOKEN cookie guide for detailed instructions.
PIXIVFE_HOST¶
Required: No (ignored if PIXIVFE_UNIXSOCKET is set)
Note
If you're not using a reverse proxy or running PixivFE inside Docker, you should set PIXIVFE_HOST=0.0.0.0. This will allow PixivFE to accept connections from any IP address or hostname. If you don't set this, PixivFE will refuse direct connections from other machines or devices on your network.
This setting specifies the hostname or IP address that PixivFE should listen on and accept incoming connections from. For example, if you want PixivFE to only accept connections from the same machine (your local computer), you can set PIXIVFE_HOST=localhost.
PIXIVFE_REPO_URL¶
Required: No
Default: https://codeberg.org/VnPower/PixivFE
The URL of the PixivFE source code repository. This is used in the about page to provide links to the project's source code and specific commit information. You can change this if you're running a fork of PixivFE and want to link to your own repository instead.
PIXIVFE_REQUESTLIMIT¶
Required: No
Request limit per half-minute.
Set to a number to enable the built-in rate limiter, e.g., PIXIVFE_REQUESTLIMIT=15.
It's recommended to enable rate limiting in the reverse proxy in front of PixivFE rather than using this.
PIXIVFE_IMAGEPROXY¶
Required: No
Default: Uses the built-in proxy.
Note
The protocol must be included in the URL, e.g., https://piximg.example.com, where https:// is the protocol used.
The URL of the image proxy server. Pixiv requires Referer: https://www.pixiv.net/ in the HTTP request headers to fetch images directly. Set this variable if you wish to use an external image proxy or are unable to get images directly from Pixiv.
See hosting an image proxy server or the list of public image proxies.
PIXIVFE_ACCEPTLANGUAGE¶
Required: No
Default: en-US,en;q=0.5
The value of the Accept-Language header used for requests to Pixiv's API. Change this to modify the response language.
PIXIVFE_TOKEN_LOAD_BALANCING¶
Required: No
Default: round-robin
Specifies the method for selecting tokens when multiple tokens are provided in PIXIVFE_TOKEN.
Valid options:
round-robin: Tokens are used in a circular order.random: A random token is selected for each request.least-recently-used: The token that hasn't been used for the longest time is selected.
This option is useful when you have multiple Pixiv accounts and want to distribute the load across them, reducing the risk of rate limiting for individual accounts by the Pixiv API.
Image proxy checker configuration¶
PixivFE includes a image proxy checker that periodically tests the pre-defined list of image proxy servers to determine which ones are working. It maintains an updated list of functional proxies that can be used to make image requests to Pixiv.
The following variables control the behavior of the proxy checker.
PIXIVFE_PROXY_CHECK_ENABLED¶
Required: No
Default: true
Controls whether the image proxy checker is enabled. Set to false to completely disable proxy checking.
When disabled, PixivFE will not perform any checks on the image proxy servers, which can be useful in environments where this behavior is not needed or causes issues.
PIXIVFE_PROXY_CHECK_INTERVAL¶
Required: No
Default: 8h
The interval between proxy checks. Defaults to 8 hours if not set.
Please specify this value in Go's time.Duration notation, e.g. 2h3m5s.
You can disable periodic checks by setting the value to 0. Then, proxies will only be checked once at server initialization.
Token management configuration¶
PixivFE implements exponential backoff for token management to manage rate limiting.
The following environment variables control how PixivFE manages token timeouts when a token encounters repeated failures. The backoff time for a token starts at the base timeout and doubles with each failure, up to the maximum backoff time.
If not set, the default values will be used.
PIXIVFE_TOKEN_MAX_RETRIES¶
Required: No
Default: 5
Maximum number of retries for token management.
PIXIVFE_TOKEN_BASE_TIMEOUT¶
Required: No
Default: 1000ms
Base timeout duration for token management.
PIXIVFE_TOKEN_MAX_BACKOFF_TIME¶
Required: No
Default: 32000ms
Maximum backoff time for token management.
Caching configuration¶
PixivFE implements a caching system for API responses to improve performance. The cache uses a Least Recently Used (LRU) eviction policy.
Each cache entry is stored with an expiration time. When a cached item is accessed, its expiration time is checked. If the item has expired, it is treated as a cache miss, and a new request is made to the Pixiv API.
To ensure that responses are properly isolated between different users, the cache key for each item is generated based on both the URL of the request and the user's pixivfe-Token cookie.
PIXIVFE_CACHE_ENABLED¶
Required: No
Default: false
Controls whether the caching system is enabled. Set to true to enable caching. When disabled, all requests will be sent directly to the Pixiv API without caching.
Other caching configuration variables (PIXIVFE_CACHE_SIZE, PIXIVFE_CACHE_TTL, and PIXIVFE_CACHE_SHORT_TTL) will have no effect if this variable is set to false.
PIXIVFE_CACHE_SIZE¶
Required: No
Default: 100
Specifies the maximum number of items that can be stored in the LRU cache. This limits the memory usage of the cache. When the cache reaches this size, the least recently used items will be evicted to make room for new entries.
PIXIVFE_CACHE_TTL¶
Required: No
Default: 60m
Specifies the default Time To Live (TTL) for cached items. This is the duration for which an item remains valid in the cache before it's considered stale and needs to be fetched again from the Pixiv API. The TTL is applied to most API responses and can safely be set to a high value.
PIXIVFE_CACHE_SHORT_TTL¶
Required: No
Default: 10s
Specifies a shorter Time To Live (TTL) for specific API endpoints that change frequently. This shorter TTL is applied to the following paths:
/ajax/discovery/artworks(used for the/discoverypage)/ajax/discovery/novels(used for the/discovery/novelspage)/ajax/illust/new(used for the/newestpage)
These paths are considered more dynamic, and the shorter TTL ensures more up-to-date content.
Feature configuration¶
PIXIVFE_POPULAR_SEARCH_ENABLED¶
Required: No
Default: false
Controls whether searching by popularity for a given tag is enabled.
Warning
This feature requires several API calls for each search, which may lead to rate limiting by the Pixiv API.
As such, enabling caching (PIXIVFE_CACHE_ENABLED=true) is recommended to minimize repeated requests.
Network proxy configuration¶
Used to set the proxy server that PixivFE will use for all requests. Not to be confused with the image proxy, which is used to comply with the Referer check required by i.pximg.net.
Requests use the proxy specified in the environment variable that matches the scheme of the request (HTTP_PROXY or HTTPS_PROXY). This selection is based on the scheme of the request being made, not on the protocol used by the proxy server itself.
HTTPS_PROXY¶
Required: No
Proxy server used for requests made over HTTPS.
HTTP_PROXY¶
Required: No
Proxy server used for requests made over plain HTTP.
Development options¶
PIXIVFE_DEV¶
Required: No
Set to any value to enable development mode, e.g., PIXIVFE_DEV=true. In development mode:
- The server will live-reload HTML templates and SCSS files.
- Caching is disabled.
- Additional debug information is logged.
- Responses are saved to
PIXIVFE_RESPONSE_SAVE_LOCATION.
This setting is useful for developers working on PixivFE itself or for troubleshooting issues in a development environment.
PIXIVFE_RESPONSE_SAVE_LOCATION¶
Required: No
Default: /tmp/pixivfe/responses
Defines where responses from the Pixiv API are saved when in development mode.
Logging Configuration¶
PixivFE uses uber-go/zap for structured, leveled logging. The following environment variables control the logging behavior.
PIXIVFE_LOG_LEVEL¶
Required: No
Default: info
Sets the minimum level of log messages to output. Valid options are:
debug: Includes all log messages, including detailed debug information.info: Includes informational messages, warnings, and errors.warn: Includes only warning and error messages.error: Includes only error messages.
PIXIVFE_LOG_OUTPUTS¶
Required: No
Default: ["stdout"]
Specifies where log messages should be sent. This can be a single output or multiple outputs separated by commas. Valid options include:
stdout: Standard output (console)stderr: Standard error- File paths: e.g.,
/var/log/pixivfe.log
Example: PIXIVFE_LOG_OUTPUTS=stdout,/var/log/pixivfe.log
PIXIVFE_LOG_FORMAT¶
Required: No
Default: console
Determines the format of log messages. Valid options are:
console: Human-readable format suitable for console outputjson: Structured JSON format, useful for log parsing and analysis tools