Detailed explanation of Nginx static service configuration (root and alias instructions)

Static files

Nginx is known for its high performance and is often used as a front-end reverse proxy server. At the same time, nginx is also a high-performance static file server. Usually, nginx is used to process the static files of the application.

There are two directives for configuring nginx static files, a root and an alias. For these two instructions, whether to add a slash after the path is often confusing. This article summarizes a more common configuration method by trying different matching rules.

Basic Configuration

Similar to the experiment about location url configuration in the article Nginx Location Url, this article also uses nginx in the vagrant virtual machine. Its basic configuration is as follows:

/etc/nginx/sites-enabled/pro.conf

server {
    listen 80 default_server;


    server_name localhost;

    access_log /var/log/nginx/pro/access.log;
    error_log /var/log/nginx/pro/error.log;

    error_page 404 /404.html;

    root /vagrant/pro;
    index index.html index.htm;
}

The project directory is as follows:

pro tree
.
├── 403.html
├── 404.html
├── index.html
├── static
│ ├── flask
│ │ └── m.png
│ └── stc.jpg
└── upload
  └── up.png

3 directories, 6 files

There are two static folders, one is static and the other is upload.

Getting to know root

root specifies the root directory of the project and is applicable to server and location. You can specify multiple locations. If location is not specified, the server or http location will be used to inherit the location.

Visit upload/2022/web/stc.jpg and you will find that the image has been returned. We haven't configured the location yet, so why can we find the file correctly? When learning the root or alias directive, the best way is to add a character to the file extension so that the file does not exist on the hard disk. Then you can see how nginx finds the file from nginx's error.log.

Visit upload/2022/web/stc.jpgx, and then check the /var/log/nginx/pro/error.log file, you can see the following error information:

2016/09/28 07:41:48 [error] 4416#0: *70 open() "/vagrant/pro/static/stc.jpgx" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /static/stc.jpgx HTTP/1.1", host: "192.168.33.10"

That is, the /vagrant/pro/static/stc.jpgx file does not exist. Indeed, we don't have this file. If the file name is correct, it can be accessed. The reason is that since root /vagrant/pro is specified in the server, nginx is looking for the file in this directory, and the address on the url is exactly the same as the path of the file.

 http://192.168.33.10 /static/stc.jpg 
 /vagrant/pro /static/stc.jpg

From this, we can guess that the address of the root directive in nginx actually replaces the host in the matched URL.

root directive

In order to verify the above conjecture, you need to write a few more locations for experiments. Add a location configuration as follows:

location ^~ /static {
  root /vagrant/pro/static;
}

Visit upload/2022/web/stc.jpg again and find that the image cannot be displayed. Check error.log and the result is as follows:

2016/09/28 07:48:57 [error] 5978#0: *71 open() "/vagrant/pro/static/static/stc.jpg" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /static/stc.jpg HTTP/1.1", host: "192.168.33.10"

nginx recognizes the address as /vargrant/pro/static/static/stc.jpg with an additional static. Applying the above rules, the combination is 192.168.33.10 == /vagrant/pro/static, and the url is /static/stc.jpg. The replacement can get /vagrant/pro/static + /static/stc.jpg. The same as error. The solution is to remove the static in the root, and you can access the image immediately.

If so, what will be the result if we name the folder static as stc?

location ^~ /static {
  root /vagrant/pro;
}

Access upload/2022/web/stc.jpg and get the error:

2016/09/28 07:54:46 [error] 5992#0: *73 open() "/vagrant/pro/static/stc.jpg" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /static/stc.jpg HTTP/1.1", host: "192.168.33.10"

Calculate the path /vagrant/pro + /static/stc.jpg. The /vagrant/pro/static/stc.jpg file cannot be found. This meets the rules mentioned above. Try to modify the location:

location ^~ /stc {
  root /vagrant/pro;
}

Because the URL has changed, you can find the image by visiting upload/2022/web/stc.jpg. Now change the stc folder back to static.

root with slash

Many people wonder whether the slash / at the end of the path should be added? The slash after static in location is related to the matched URL, so I will not go into details. The slash / in the path of root can be determined by experiment. Configure the location as follows:

location ^~ /static/ {
  root /vagrant/pro/;
}

Access upload/2022/web/stc.jpg. Everything is normal. Access upload/2022/web/stc.jpg. The error is that the "/vagrant/pro/static/stc.jpgs" file cannot be found.

If you follow the rule of replacing host with root, the replacement process is:

/vagrant/pro/ + /static/stc.jpg == /vagrant/pro//static/stc.jpg. On *nix systems, multiple slashes and a single slash are equivalent, that is, /vagrant/pro//static/stc.jpg is the same as /vagrant/pro/static/stc.jpg.

In this way, the effect is the same whether there is a slash after the root path or not. In this case, someone will definitely think of this configuration:

location ^~ static/ {
  root /vagrant/pro;
}

If the algorithm above is used before installation, then it should be /vagrant/pro + static/stc.jpg, and the sum should be /vagrant/prostatic/stc.jpg. It should be wrong, but in fact the picture can be accessed. Something strange?
If you understand the URL matching rules of nginx location in the previous article, you should be able to see that ^~ static/ cannot match. Modify location

location ^~ static/ {
  rewrite ^ http://google.com;
  # root /vagrant/pro;
}

You can still get the image by visiting upload/2022/web/stc.jpg. There is no jump to Google, which means there is no match ^~ static/.

In fact, the principle is very simple. Remember our first experiment, when we had not configured the location, we could still return the image. That’s right. Although ^~ static/ does not match, the outer server defines the root as /vagrant/pro, so the search for the image returns normally. Then comment out the outer root and access it again. At this point you will get a 404 error. Check the error as follows:

2016/09/28 08:18:15 [error] 6227#0: *82 open() "/usr/share/nginx/html/static/stc.jpg" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /static/stc.jpg HTTP/1.1", host: "192.168.33.10"

/usr/share/nginx/html/static/stc.jpg, which means that even if the root is not specified, nginx has a root by default, /usr/share/nginx/html. Of course, this configuration has nothing to do with ^~ static/.

If ~ static/stc.jpgs? is found, the result is correct. Therefore, the image cannot be parsed correctly when it is accessed. Therefore, there is no such situation as /vagrant/pro + static/stc.jpg. The key to understanding here is to replace host with root and add the matched url. The matched url of course includes the leading slash, while the matched part of the url does not.
For ~ static/stc.jpgs? mode, access urlupload/2022/web/stc.jpg

• The matched url is /static/stc.jpg
• The matching part of the url is static/stc.jpg

It is very important to master this, as it is directly related to the relationship between the alias command and the slash later.

For the root directive, we can summarize.

1. For the matched URL address, replace the root path in the matched location with the host of the access URL to get the real address of the file. (Multiple slashes are equivalent to one slash)
2. If the location does not match, look for a root at the outer level to replace it.
3. The slash mark at the end of the root directive is optional.

The alias directive

For root, the operation is very simple. Just replace the root address with the host, which is the file's hard disk path (real address). For alise, it does not replace the matched URL address, but replaces the matched part of the URL. There can be multiple alias directives.
Adding a location is almost the same as adding a root:

location ^~ /upload {
  alias /vagrant/pro;
}

There is no image when accessing upload/2022/web/up.png. Check the error and you will get:

2016/09/28 08:36:18 [error] 6312#0: *90 open() "/vagrant/pro/up.png" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /upload/up.png HTTP/1.1", host: "192.168.33.10"

It can be seen that the alias pattern is not /vagrant/pro + /upload/up.png, but /vagrant/pro + /up.png.

The word alias is very commonly used in computers. Its literal meaning is "alias". As the name suggests, it means changing the name. The actual replacement rule is to replace the matching URL address with the path in alias. For example, the replacement process of the above example can be simulated as follows:

To modify the access to the image, modify the locaton as follows:

location ^~ /upload {
  alias /vagrant/pro/upload;
}

At this time, you can get the correct image by visiting upload/2022/web/up.png. The calculation process above is as follows:

From the results, we can see that the file path is found correctly. If the alias instruction path is added with a slash, the calculated file path is:

/upload == /vagrant/pro/upload
/vagrant/pro/upload/ + /up.png

Multiple slashes are legal. Equivalent to the case with a single slash.

Modify the locaiton as follows:

location ^~ /upload/ {
  alias /vagrant/pro/upload;
}

The matching URL becomes /upload/ + up.jpg, and the result of the substitution is /vagrant/pro/upload + up.png. However, the path /vagrant/pro/uploadup.png is illegal. The substitution error can also be seen from the error:

2016/09/28 08:52:44 [error] 6452#0: *92 open() "/vagrant/pro/uploadup.png" failed (2: No such file or directory), client: 192.168.33.1, server: localhost, request: "GET /upload/up.png HTTP/1.1", host: "192.168.33.10"

The solution is also very simple, just change /vagrant/pro/upload to /vagrant/pro/upload/. It can be seen that the slash at the end of alias is not dispensable like the root directive. Whether it is needed depends on the URL matching pattern of the location.

In the previous root mode, the case of a slash without a root (~ static/stc.jpgs?) was taken into account. It would be difficult to catch errors in the alias case. If the location is configured as follows:

location ^~ upload/ {
   alias /vagrant/pro/upload/;
}

The replacement file path should be /vagrant/pro/upload/up.png, but in actual testing, configuring the alias in this way will always result in a 301 redirect. If the alias directory does not have autoindex turned on, a 403 error will be thrown. The specific situation is not yet known, and I don’t know if it is a bug in nginx. To avoid this situation, when using alias, try not to configure the location as ^~ upload/ mode, and do not specify the URL from the root, otherwise it will look out of place.

A big advantage of using alise as an alias over root is that the path on the URL does not necessarily have to be the same as the file path, because alise does not replace the host, but replaces the matching part of the host. Modify the configuration as follows:

location ^~ /upload/ {
  alias /vagrant/pro/static/;
}

Accessing upload/2022/web/stc.jpg or upload/2022/web/m.png can correctly access the files in the static directory, even though the URL is upload.

The replacement rule is also simple, /upload/ == /vagrant/pro/static/ gets /vagrant/pro/static/ + stc.jpg or /vagrant/pro/static/ + flask/m.png.

Summarize

In nginx's static file configuration, both root and alias directives can be implemented. To avoid confusion, try not to write URL patterns without a root path, that is, avoid starting with static/. The slash of the root path needs to be retained. It would be strange to have no root path.

The difference between root and alias lies in the replacement part. In root mode, the path configured by root will replace the host in the matched url. Alias ​​replaces the matching part of the url with the path it specifies. The slash in the command has no effect on the root command, and for alise, it can be matched according to the replacement rules.

root directive

location /dir/ 
root root_path -> http://host/dir/file.txt -> root_path/dir/file.txt

The alias directive

location /dir
alias alias_path -> http://host /dir /file.txt -> alias_path/file.txt

location /dir/ 
alias alias_path/ -> http://host /dir/ file.txt -> alias_path/file.txt

After understanding root and alias, it is usually best to configure the root of a project and use aliases for other folders. After all, aliases are more flexible.

The above is the full content of this article. I hope it will be helpful for everyone’s study. I also hope that everyone will support 123WORDPRESS.COM.